@web-applets/sdk 0.0.7 → 0.0.8

package/README.md

@@ -2,14 +2,18 @@
 
 > An open SDK to create interoperable actions & views for agents – _a web of capabilities!_
 
-🔗 [Community Applets Repo](https://github.com/unternet-co/community-applets)
+🔗 [Community Applets Repo](https://github.com/unternet-co/community-applets) | 🔗 [Community Mailing List](https://groups.google.com/a/unternet.co/g/community)
 
 ## What is it?
 
 Web Applets is a specification for modular, local web software that can be read and used by both humans and machines. Web Applets aims to be an interoperabe application layer for agents – instead of chatbots that can only interact in plain text, Web Applets allow them to actuate real software, read the results, and render rich, graphical views in response.
 
+In short, your model can use & respond with artibrary bits of web UI that a human can then interact with – a map, a rich text document, an item on Amazon with a purchase button, whatever you can build with the web you can turn it into an applet that an agent can use and display.
+
 Did we mention it's _interoperable_? We think the future of software should be open & collaborative, not locked down to a single platform.
 
+For more, see [why](./docs/why.md).
+
 ## Getting started
 
 Install the applets SDK & CLI:

package/dist/client.d.ts

@@ -1,7 +1,10 @@
-import { AppletAction, AppletHeader, AppletMessage, ActionParams, AppletManifest } from './types';
-export declare function getHeaders(url: string): Promise<AppletHeader[]>;
-export declare function getManifests(url: string): Promise<any[]>;
-export declare function load(url: string, container: HTMLIFrameElement): Promise<Applet>;
+import { AppletAction, AppletHeader, AppletMessage, ActionParams, AppletManifest, AppletMessageType, AppletMessageCallback, AppletManifestDict } from './types';
+export declare function list(url: string): Promise<AppletManifestDict>;
+interface AppletOpts {
+    headless?: boolean;
+    unsafe?: boolean;
+}
+export declare function load(url: string, container?: HTMLIFrameElement, opts?: AppletOpts): Promise<Applet>;
 export declare class Applet<T = unknown> extends EventTarget {
     #private;
     actions: AppletAction[];
@@ -20,5 +23,10 @@ export declare class Applet<T = unknown> extends EventTarget {
     onstateupdated(event: CustomEvent): void;
     disconnect(): void;
     dispatchAction(actionId: string, params: ActionParams): Promise<AppletMessage<any>>;
+    send(message: AppletMessage): Promise<AppletMessage<any>>;
+    on(messageType: AppletMessageType, callback: AppletMessageCallback): Promise<void>;
 }
 export declare function loadManifest(url: string): Promise<AppletManifest>;
+export declare function getHeaders(url: string): Promise<AppletHeader[]>;
+export declare function getManifests(url: string): Promise<any[]>;
+export {};

package/dist/client.js

@@ -9,73 +9,72 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     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_state;
+var _Applet_instances, _Applet_state, _Applet_dispatchEvent;
 import { AppletMessage, } from './types';
-const hiddenRoot = document.createElement('div');
-hiddenRoot.style.display = 'none';
-document.body.appendChild(hiddenRoot);
-export async function getHeaders(url) {
+const hiddenContainer = document.createElement('iframe');
+hiddenContainer.style.display = 'none';
+document.body.appendChild(hiddenContainer);
+export async function list(url) {
     url = parseUrl(url);
     try {
         const request = await fetch(`${url}/manifest.json`);
         const appManifest = await request.json();
-        const appletHeaders = appManifest.applets;
-        return appletHeaders ?? [];
+        const appletUrls = appManifest.applets;
+        const manifests = {};
+        const manifestRequests = appletUrls.map(async (appletUrl) => {
+            appletUrl = parseUrl(appletUrl, url);
+            const request = await fetch(`${appletUrl}/manifest.json`);
+            const manifest = await request.json();
+            manifests[appletUrl] = manifest;
+        });
+        await Promise.all(manifestRequests);
+        return manifests;
     }
     catch {
-        return [];
+        return {};
     }
 }
-export async function getManifests(url) {
-    url = parseUrl(url);
-    const request = await fetch(`${url}/manifest.json`);
-    const headers = (await request.json()).applets;
-    const manifests = await Promise.all(headers.map(async (header) => {
-        const appletUrl = parseUrl(header.url);
-        const request = await fetch(`${appletUrl}/manifest.json`);
-        return await request.json();
-    }));
-    return manifests ?? [];
-}
-export async function load(url, container) {
+const defaultOpts = {
+    headless: false,
+    unsafe: false,
+};
+export async function load(url, container, opts) {
+    const _opts = Object.assign(defaultOpts, opts ?? {});
+    if (!container) {
+        container = hiddenContainer;
+        _opts.headless = true;
+    }
+    if (!_opts.unsafe)
+        container.setAttribute('sandbox', 'allow-scripts allow-forms');
     url = parseUrl(url);
     const manifest = await loadManifest(`${url}`);
     const applet = new Applet();
     applet.manifest = manifest;
-    applet.actions = manifest.actions; // let the events set this later
+    applet.actions = manifest.actions;
     applet.container = container;
     container.src = applet.manifest.entrypoint;
-    if (!container.isConnected)
-        hiddenRoot.appendChild(container);
     return new Promise((resolve) => {
-        window.addEventListener('message', (message) => {
-            if (message.source !== container.contentWindow)
-                return;
-            if (message.data.type === 'ready')
-                resolve(applet);
+        applet.on('ready', () => {
+            const initMessage = new AppletMessage('init', {
+                headless: _opts.headless,
+            });
+            applet.send(initMessage);
+            resolve(applet);
         });
     });
 }
 export class Applet extends EventTarget {
     constructor() {
         super();
+        _Applet_instances.add(this);
         this.actions = [];
         _Applet_state.set(this, void 0);
-        window.addEventListener('message', (message) => {
-            if (message.source !== this.container.contentWindow)
-                return;
-            if (message.data.type === 'state') {
-                __classPrivateFieldSet(this, _Applet_state, message.data.state, "f");
-                this.dispatchEvent(new CustomEvent('stateupdated', { detail: message.data.detail }));
-                this.onstateupdated(message.data.state);
-            }
-            if (message.data.type === 'resize') {
-                this.resizeContainer(message.data.dimensions);
-            }
-            this.container.contentWindow?.postMessage({
-                type: 'resolve',
-                id: message.data.id,
-            }, '*');
+        this.on('state', (message) => {
+            __classPrivateFieldSet(this, _Applet_state, message.state, "f");
+            __classPrivateFieldGet(this, _Applet_instances, "m", _Applet_dispatchEvent).call(this, 'stateupdated', message.state);
+        });
+        this.on('resize', (message) => {
+            this.resizeContainer(message.dimensions);
         });
     }
     get state() {
@@ -83,8 +82,7 @@ export class Applet extends EventTarget {
     }
     set state(state) {
         __classPrivateFieldSet(this, _Applet_state, state, "f");
-        const stateMessage = new AppletMessage('state', { state });
-        this.container.contentWindow?.postMessage(stateMessage.toJson(), '*');
+        this.send(new AppletMessage('state', { state }));
     }
     toJson() {
         return Object.fromEntries(Object.entries(this).filter(([_, value]) => {
@@ -98,7 +96,7 @@ export class Applet extends EventTarget {
         }));
     }
     resizeContainer(dimensions) {
-        this.container.style.height = `${dimensions.height}px`;
+        this.container.style.height = `${dimensions.height + 2}px`;
         // if (!this.#styleOverrides) {
         //   this.#container.style.height = `${dimensions.height}px`;
         // }
@@ -110,14 +108,15 @@ export class Applet extends EventTarget {
             actionId,
             params,
         });
-        this.container.contentWindow?.postMessage(requestMessage.toJson(), '*');
+        return await this.send(requestMessage);
+    }
+    async send(message) {
+        this.container.contentWindow?.postMessage(message.toJson(), '*');
         return new Promise((resolve) => {
             const listener = (messageEvent) => {
-                if (messageEvent.source !== this.container.contentWindow)
-                    return;
                 const responseMessage = new AppletMessage(messageEvent.data.type, messageEvent.data);
                 if (responseMessage.type === 'resolve' &&
-                    responseMessage.id === requestMessage.id) {
+                    responseMessage.id === message.id) {
                     window.removeEventListener('message', listener);
                     resolve(responseMessage);
                 }
@@ -125,20 +124,37 @@ export class Applet extends EventTarget {
             window.addEventListener('message', listener);
         });
     }
+    async on(messageType, callback) {
+        const listener = async (messageEvent) => {
+            if (messageEvent.source !== this.container.contentWindow)
+                return;
+            if (messageEvent.data.type !== messageType)
+                return;
+            const message = new AppletMessage(messageEvent.data.type, messageEvent.data);
+            await callback(message);
+            this.container.contentWindow?.postMessage(new AppletMessage('resolve', { id: message.id }), '*');
+        };
+        window.addEventListener('message', listener);
+    }
 }
-_Applet_state = new WeakMap();
+_Applet_state = new WeakMap(), _Applet_instances = new WeakSet(), _Applet_dispatchEvent = function _Applet_dispatchEvent(id, detail) {
+    if (typeof this[`on${id}`] === 'function') {
+        this[`on${id}`](detail);
+    }
+    this.dispatchEvent(new CustomEvent(id, { detail }));
+};
+/* Helpers */
 function parseUrl(url, base) {
     if (['http', 'https'].includes(url.split('://')[0])) {
         return url;
     }
-    let path = url;
-    if (path.startsWith('/'))
-        path = path.slice(1);
-    if (path.endsWith('/'))
-        path = path.slice(0, -1);
+    let path = trimSlashes(url);
     url = `${base || window.location.origin}/${path}`;
     return url;
 }
+function trimSlashes(str) {
+    return str.replace(/^\/+|\/+$/g, '');
+}
 export async function loadManifest(url) {
     url = parseUrl(url);
     const request = await fetch(`${url}/manifest.json`);
@@ -149,3 +165,26 @@ export async function loadManifest(url) {
     appletManifest.entrypoint = parseUrl(appletManifest.entrypoint, url);
     return appletManifest;
 }
+export async function getHeaders(url) {
+    url = parseUrl(url);
+    try {
+        const request = await fetch(`${url}/manifest.json`);
+        const appManifest = await request.json();
+        const appletHeaders = appManifest.applets;
+        return appletHeaders ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function getManifests(url) {
+    url = parseUrl(url);
+    const request = await fetch(`${url}/manifest.json`);
+    const headers = (await request.json()).applets;
+    const manifests = await Promise.all(headers.map(async (header) => {
+        const appletUrl = parseUrl(header.url);
+        const request = await fetch(`${appletUrl}/manifest.json`);
+        return await request.json();
+    }));
+    return manifests ?? [];
+}

package/dist/context.d.ts

@@ -3,12 +3,15 @@ import { ActionHandlerDict, AppletMessage, AppletMessageType, AppletMessageCallb
  * Context
  */
 export declare class AppletContext<StateType = any> extends EventTarget {
+    #private;
     client: AppletClient;
     actionHandlers: ActionHandlerDict;
-    state: StateType;
+    headless: boolean;
     connect(): this;
     setActionHandler<T extends ActionParams>(actionId: string, handler: ActionHandler<T>): void;
-    setState(state: StateType): Promise<void>;
+    set state(state: StateType);
+    get state(): StateType;
+    setState(state: StateType, shouldRender?: boolean): Promise<void>;
     onload(): Promise<void> | void;
     onready(): Promise<void> | void;
     onrender(): void;

package/dist/context.js

@@ -1,3 +1,15 @@
+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 __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 _AppletContext_state;
 import { AppletMessage, } from './types';
 /**
  * Context
@@ -6,6 +18,8 @@ export class AppletContext extends EventTarget {
     constructor() {
         super(...arguments);
         this.actionHandlers = {};
+        _AppletContext_state.set(this, void 0);
+        this.headless = false;
     }
     connect() {
         this.client = new AppletClient();
@@ -34,11 +48,24 @@ export class AppletContext extends EventTarget {
             }
         });
         resizeObserver.observe(document.querySelector('html'));
+        this.client.on('init', (message) => {
+            const initMessage = message;
+            this.headless = initMessage.headless;
+        });
         this.client.on('state', (message) => {
             if (!isStateMessage(message)) {
                 throw new TypeError("Message doesn't match type StateMessage");
             }
-            this.setState(message.state);
+            // Don't render when state updates match the current state
+            // this retains cursor positions in text fields, for example
+            if (JSON.stringify(message.state) === JSON.stringify(__classPrivateFieldGet(this, _AppletContext_state, "f")))
+                return;
+            __classPrivateFieldSet(this, _AppletContext_state, message.state, "f");
+            // BUG: For some reason regular applets were loading headless, when instantiated not on a page reload
+            // if (!this.headless) {
+            this.onrender();
+            this.dispatchEvent(new CustomEvent('render'));
+            // }
         });
         this.client.on('action', async (message) => {
             if (!isActionMessage(message)) {
@@ -47,24 +74,32 @@ export class AppletContext extends EventTarget {
             if (Object.keys(this.actionHandlers).includes(message.actionId)) {
                 await this.actionHandlers[message.actionId](message.params);
             }
-            message.resolve();
         });
         return this;
     }
     setActionHandler(actionId, handler) {
         this.actionHandlers[actionId] = handler;
     }
-    async setState(state) {
+    set state(state) {
+        this.setState(state);
+    }
+    get state() {
+        return __classPrivateFieldGet(this, _AppletContext_state, "f");
+    }
+    async setState(state, shouldRender) {
         const message = new AppletMessage('state', { state });
         await this.client.send(message);
-        this.state = state;
-        this.dispatchEvent(new CustomEvent('render'));
-        this.onrender(); // TODO: Should come from client? Or stay here, and only activate if mounted? Need a control for mounting.
+        __classPrivateFieldSet(this, _AppletContext_state, state, "f");
+        if (shouldRender !== false && !this.headless) {
+            this.onrender();
+            this.dispatchEvent(new CustomEvent('render'));
+        }
     }
     onload() { }
     onready() { }
     onrender() { }
 }
+_AppletContext_state = new WeakMap();
 function isActionMessage(message) {
     return message.type === 'action';
 }
@@ -76,14 +111,12 @@ function isStateMessage(message) {
  */
 class AppletClient {
     on(messageType, callback) {
-        window.addEventListener('message', (messageEvent) => {
+        window.addEventListener('message', async (messageEvent) => {
             if (messageEvent.data.type !== messageType)
                 return;
             const message = new AppletMessage(messageEvent.data.type, messageEvent.data);
-            message.resolve = () => {
-                window.parent.postMessage(new AppletMessage('resolve', { id: message.id }), '*');
-            };
-            callback(message);
+            await callback(message);
+            window.parent.postMessage(new AppletMessage('resolve', { id: message.id }), '*');
         });
     }
     send(message) {

package/dist/types.d.ts

@@ -1,14 +1,19 @@
 export interface AppletManifest {
     type: 'applet';
     name: string;
-    description: string;
+    description?: string;
     icon?: string;
-    entrypoint: string;
-    actions: AppletAction[];
+    frameless?: boolean;
+    entrypoint?: string;
+    actions?: AppletAction[];
+}
+export interface AppletManifestDict {
+    [url: string]: AppletManifest;
 }
 export interface AppletAction {
     id: string;
-    description: string;
+    name?: string;
+    description?: string;
     params?: ActionParamSchema;
 }
 export interface AppletHeader {
@@ -23,12 +28,12 @@ export interface AppletHeader {
         };
     }[];
 }
-export type AppletState = Record<string, Serializable>;
+export type AppletState = any;
 export type ActionParamSchema = Record<string, {
     description: string;
     type: 'string';
 }>;
-export type ActionParams = Record<string, unknown>;
+export type ActionParams<T = any> = Record<string, T>;
 export type ActionHandlerDict = {
     [key: string]: ActionHandler<any>;
 };
@@ -38,11 +43,22 @@ export interface AppletStateMessage<T = any> extends AppletMessage {
     type: 'state';
     state: T;
 }
+export interface AppletResizeMessage extends AppletMessage {
+    type: 'resize';
+    dimensions: {
+        height: number;
+        width: number;
+    };
+}
 export interface AppletActionMessage<T = any> extends AppletMessage {
     type: 'action';
     actionId: string;
     params: T;
 }
+export interface AppletInitMessage extends AppletMessage {
+    type: 'init';
+    headless: boolean;
+}
 export declare class AppletMessage<T = any> {
     type: AppletMessageType;
     id: string;
@@ -53,9 +69,5 @@ export declare class AppletMessage<T = any> {
     };
     resolve(): void;
 }
-export type AppletMessageType = 'action' | 'render' | 'state' | 'ready' | 'resolve' | 'resize';
-export type AppletMessageCallback = (message: AnyAppletMessage) => void;
-type Serializable = string | number | boolean | null | Serializable[] | {
-    [key: string]: Serializable;
-};
-export {};
+export type AppletMessageType = 'action' | 'actions' | 'render' | 'state' | 'init' | 'ready' | 'resolve' | 'resize';
+export type AppletMessageCallback = (message: AnyAppletMessage) => Promise<void> | void;

package/dist/web-component/index.d.ts

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

package/dist/web-component/index.js

@@ -0,0 +1,52 @@
+import { applets } from '../index';
+class AppletView extends HTMLElement {
+    connectedCallback() {
+        const styles = document.createElement('style');
+        styles.textContent = this.styles;
+        this.appendChild(styles);
+        this.container = document.createElement('iframe');
+        this.appendChild(this.container);
+    }
+    get styles() {
+        return /*css*/ `
+    applet-frame {
+      display: flex;
+      flex-direction: column;
+    }
+
+    applet-frame iframe {
+      border: none;
+    }
+
+    applet-frame:not(.frameless) {
+      border: 1px solid #ddd;
+    }
+
+    applet-frame.frameless {
+      padding: 0 7px;
+    }
+    `;
+    }
+    set url(url) {
+        setTimeout(() => this.loadApplet(url), 1);
+    }
+    async loadApplet(url) {
+        if (!this.container)
+            return;
+        this.applet = await applets.load(url, this.container);
+        if (this.applet.manifest.frameless)
+            this.classList.add('frameless');
+        this.applet.onstateupdated = () => {
+            this.dispatchEvent(new CustomEvent('stateupdated', { detail: this.applet.state }));
+        };
+        this.dispatchEvent(new CustomEvent('load'));
+    }
+    set state(state) {
+        if (this.applet)
+            this.applet.state = state;
+        this.addEventListener('load', () => {
+            this.applet.state = state;
+        });
+    }
+}
+customElements.define('applet-frame', AppletView);

package/dist/web-components/applet-frame.d.ts

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

package/dist/web-components/applet-frame.js

@@ -0,0 +1,52 @@
+import { applets } from '../index.js';
+class AppletFrame extends HTMLElement {
+    connectedCallback() {
+        const styles = document.createElement('style');
+        styles.textContent = this.styles;
+        this.appendChild(styles);
+        this.container = document.createElement('iframe');
+        this.appendChild(this.container);
+    }
+    get styles() {
+        return /*css*/ `
+    applet-frame {
+      display: flex;
+      flex-direction: column;
+    }
+
+    applet-frame iframe {
+      border: none;
+    }
+
+    applet-frame:not(.frameless) {
+      border: 1px solid #ddd;
+    }
+
+    applet-frame.frameless {
+      padding: 0 7px;
+    }
+    `;
+    }
+    set url(url) {
+        setTimeout(() => this.loadApplet(url), 1);
+    }
+    async loadApplet(url) {
+        if (!this.container)
+            return;
+        this.applet = await applets.load(url, this.container);
+        if (this.applet.manifest.frameless)
+            this.classList.add('frameless');
+        this.applet.onstateupdated = () => {
+            this.dispatchEvent(new CustomEvent('stateupdated', { detail: this.applet.state }));
+        };
+        this.dispatchEvent(new CustomEvent('load'));
+    }
+    set state(state) {
+        if (this.applet)
+            this.applet.state = state;
+        this.addEventListener('load', () => {
+            this.applet.state = state;
+        });
+    }
+}
+customElements.define('applet-frame', AppletFrame);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web-applets/sdk",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "The Web Applets SDK, for creating & hosting Web Applets.",
   "author": "Rupert Manfredi <rupert@unternet.co>",
   "license": "MIT",
@@ -25,6 +25,7 @@
     "typescript": "^5.6.2"
   },
   "dependencies": {
+    "marked": "^14.1.3",
     "vite": "^5.4.7"
   }
 }