@web-applets/sdk 0.1.0 → 0.1.2

package/README.md

@@ -2,34 +2,24 @@
 
 > An open spec & SDK for creating apps that agents can use.
 
-🔗 [Applets Repo](https://github.com/unternet-co/community-applets) | 🔗 [Mailing List](https://groups.google.com/a/unternet.co/g/community) | 🔗 [Applets Chat Demo](https://github.com/unternet-co/applets-chat)
+💌 [Mailing List](https://groups.google.com/a/unternet.co/g/community)
 
 ## What is it?
 
-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. Think of them a bit like artifacts, but they do stuff!
+**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.
 
-![Demo of a web applets chatbot](./docs/assets/applets-chat-demo.gif)
-
-Web Applets are modular pieces of web software that:
-
-- **Can be used directly by humans with rich, graphical interfaces**
-- **Can be understood and operated by AI through a clear protocol**
-- **Run locally in your environment, not on distant servers**
-- **Share context and state with their environment**
-- **Can be freely combined and composed**
+Think of them a bit like Claude artifacts, but they _do stuff_ & _work anywhere_!
 
-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.
+![Demo of a web applets chatbot](./docs/assets/applets-chat-demo.gif)
 
-## Key Features
+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!
 
-- **Built on Web Standards:** Create applets using familiar web technologies (HTML, CSS, JavaScript)
+- **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, not platform lock-in
-
-Web Applets aims to do for AI-enabled software what the web did for documents - create an open platform where anyone can build, share, and connect applications. We believe the future of software should be built on open collaboration, not tight integration with closed platforms.
+- **Open Standard:** Designed for interoperability across clients, not platform lock-in
 
 ## Example
 
@@ -75,6 +65,17 @@ context.ondata = () => {
 
 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:
@@ -93,7 +94,7 @@ Inside the generated folder, you'll find a basic web app setup:
 
 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.
 
-![A screenshot showing the 'playground' editing UI, with a web applets showing 'Hello, Web Applets'](docs/assets/web-applets-playground.png)
+![A screenshot showing the 'playground' editing UI, with a web applets showing 'Hello, Web Applets'](docs/assets/web-applets-inspector.png)
 
 ## Integrating Web Applets into your client
 
@@ -136,7 +137,7 @@ applet.data = { name: 'Ada Lovelace' };
 
 This is a community project, and we're open to community members discussing the project direction, and submitting code!
 
-To join the conversation, visit the Applets mailing list at [groups.google.com/a/unternet.co/g/community](https://groups.google.com/a/unternet.co/g/community). You can also find more about the company that's kicking off this work at [unternet.co](https://unternet.co)
+To join the conversation, visit the Applets mailing list [here](https://groups.google.com/a/unternet.co/g/community). You can also find more about the company that's kicking off this work at [unternet.co](https://unternet.co)
 
 ## License
 

package/dist/core/applet.d.ts

@@ -1,4 +1,4 @@
-import { AppletAction, AppletMessage, ActionParams, AppletManifest, AppletDataEvent, AppletResizeEvent, AppletActionsEvent, AppletMessageRelay, AppletReadyEvent } from './shared';
+import { AppletAction, ActionParams, AppletManifest, AppletDataEvent, AppletResizeEvent, AppletActionsEvent, AppletMessageRelay, AppletReadyEvent } from './shared';
 export declare function load(url: string, container?: HTMLIFrameElement): Promise<Applet>;
 export interface AppletOptions {
     manifest: AppletManifest;
@@ -10,7 +10,7 @@ export declare class Applet<T = any> extends EventTarget {
     actions: AppletAction[];
     container: HTMLIFrameElement;
     constructor(manifest: AppletManifest, targetWindow: Window);
-    dispatchAction(actionId: string, params?: ActionParams): Promise<AppletMessage>;
+    dispatchAction(actionId: string, params?: ActionParams): Promise<import("./shared").AppletMessage>;
     get data(): T;
     set data(data: T);
     get manifest(): AppletManifest;

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;
@@ -91,7 +90,7 @@ export declare class AppletActionMessage extends AppletMessage {
 export declare class AppletInitMessage extends AppletMessage {
     constructor();
 }
-export type AppletMessageType = 'action' | 'actions' | 'data' | 'init' | 'ready' | 'resolve' | 'resize';
+export type AppletMessageType = 'action' | 'actions' | 'data' | 'init' | 'ready' | 'style' | 'resolve' | 'resize';
 export type AppletMessageCallback = (message: AppletMessage) => Promise<void> | void;
 export declare class AppletDataEvent extends Event {
     data: any;

package/dist/core/shared.js

@@ -9,10 +9,14 @@ export async function loadManifest(pageUrl) {
         const parser = new DOMParser();
         const doc = parser.parseFromString(html, 'text/html');
         const linkElem = doc.querySelector('link[rel="manifest"]');
-        const manifestUrl = parseUrl(linkElem.href);
+        const href = linkElem.getAttribute('href');
+        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/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('/')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web-applets/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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;
-// }