@metapages/metapage 1.8.29 → 1.9.0

package/README.md

@@ -1,38 +1,173 @@
-# [Metapages](https://docs.metapage.io/docs)
+# @metapages/metapage
 
-A _metapage_ is a set of connected iframes (_metaframes_).
+> Build composable, interconnected web applications using iframes and data pipes
 
-- Examples: [https://metapage.io](https://metapage.io)
-- Documentation: [https://docs.metapage.io/docs](https://docs.metapage.io/docs)
-- Online tests and conversion tools: [https://module.metapage.io](https://module.metapage.io)
-- Example javascript component: [https://js.mtfm.io](https://js.mtfm.io)
+[![npm version](https://badge.fury.io/js/%40metapages%2Fmetapage.svg)](https://www.npmjs.com/package/@metapages/metapage)
 
-Each component iframe runs the metapage module and establishes input/output pipes. Now you can create, edit, and embed whole complex applications directly in your own apps, or simply create using the [metapage editor]((https://metapage.io) and publish and share immediately.
+**@metapages/metapage** is a JavaScript library that lets you create and embed interactive workflows in the browser by connecting independent iframe components together through input/output data pipes.
 
-## Quickstart metapage
+## Quick Links
 
-Load and render a metapage definition
+- 📚 [Full Documentation](https://docs.metapage.io/docs)
+- 🎨 [Live Examples](https://metapage.io)
+- 🛠️ [Interactive Tools](https://module.metapage.io)
+- 💻 [Example Component](https://js.mtfm.io)
+
+## What is this?
+
+A **metapage** is a web application made up of connected iframes called **metaframes**. Each metaframe can:
+
+- Receive data from other metaframes (inputs)
+- Send data to other metaframes (outputs)
+- Run independently (JavaScript, Docker containers, markdown editors, or any web component)
+
+Think of it like a visual programming environment where each component is a full web application that can communicate with others through simple JSON data pipes.
+
+## Installation
+
+```bash
+npm install @metapages/metapage
+```
+
+Or use directly from CDN:
+
+```javascript
+import {
+  renderMetapage,
+  Metapage,
+  Metaframe,
+} from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.8.35";
+```
+
+## Quick Start
+
+### Rendering a Metapage
+
+The simplest way to embed a workflow is using `renderMetapage`:
 
 ```javascript
-import { renderMetapage } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.8.15";
+import { renderMetapage } from "@metapages/metapage";
 
-// download a metapage definition from metapage.io
-// or just use your own definition JSON
+// Fetch a metapage definition (or define your own JSON)
 const response = await fetch(
   "https://metapage.io/m/87ae11673508447e883b598bf7da9c5d/metapage.json",
 );
-const metapageDefinition = await response.json();
-await renderMetapage({
-  definition: metapageDefinition,
-  rootDiv: document.getElementById("metapage-container"),
+const definition = await response.json();
+
+// Render it
+const { setInputs, dispose } = await renderMetapage({
+  definition,
+  rootDiv: document.getElementById("container"),
 });
 ```
 
-The rendered workflow:
+The `renderMetapage` function the `react-grid-layout` layout in `metapage.json`:
+
+```json
+{
+  "meta": {
+    "layouts": {
+      "react-grid-layout": {
+        ...
+      }
+    }
+  }
+}
+```
+
+[Implentation in source code](https://github.com/metapages/metapage/blob/2ef8bd7bfb151ad1616da46aa9797bcf2b1c3d78/app/libs/src/metapage/metapageRenderer.ts#L204)
+
+### Creating a Metaframe (Inside an iframe)
 
-![Logo](https://unpkg.com/@metapages/metapage/assets/example-01.png)
+If you're building a component to use in a metapage:
 
-## Full example
+```javascript
+import { Metaframe } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.8.35";
+
+const metaframe = new Metaframe();
+
+// Listen for input data from other metaframes
+metaframe.onInput("data", (value) => {
+  console.log("Received:", value);
+  // Process the data and send output
+  metaframe.setOutput("result", value.toUpperCase());
+});
+
+// Or listen to all inputs at once
+metaframe.onInputs((inputs) => {
+  console.log("All inputs:", inputs);
+});
+```
+
+## Core Concepts
+
+### Metapage Definition
+
+A metapage is defined using JSON that specifies which metaframes to load and how they connect:
+
+```javascript
+{
+  "version": "2",
+  "metaframes": {
+    "input": {
+      "url": "https://editor.mtfm.io/#?hm=disabled"
+    },
+    "processor": {
+      "url": "https://js.mtfm.io/",
+      "inputs": [
+        {
+          "metaframe": "input",
+          "source": "text",
+          "target": "code"
+        }
+      ]
+    },
+    "output": {
+      "url": "https://markdown.mtfm.io/",
+      "inputs": [
+        {
+          "metaframe": "processor",
+          "source": "output"
+        }
+      ]
+    }
+  }
+}
+```
+
+This creates a pipeline: `input` → `processor` → `output`
+
+### Data Pipes
+
+Pipes connect metaframe outputs to other metaframe inputs:
+
+```javascript
+{
+  "metaframe": "sourceMetaframeId",  // Where data comes from
+  "source": "outputPipeName",         // Name of the output pipe
+  "target": "inputPipeName"           // Name of the input pipe (optional, defaults to source)
+}
+```
+
+### Working with Data
+
+The library automatically handles serialization of complex data types:
+
+```javascript
+// In a metaframe - these are automatically serialized when sent between iframes
+metaframe.setOutput("file", new File([blob], "data.txt"));
+metaframe.setOutput("binary", new Uint8Array([1, 2, 3]));
+metaframe.setOutput("buffer", arrayBuffer);
+
+// And automatically deserialized when received
+metaframe.onInput("file", (file) => {
+  console.log(file instanceof File); // true
+});
+```
+
+## Usage Examples
+
+### Full HTML Example
 
 ```html
 <!DOCTYPE html>
@@ -40,61 +175,300 @@ The rendered workflow:
   <head>
     <meta charset="utf-8" />
     <style>
-      * {
-        box-sizing: border-box;
+      body {
         margin: 0;
         padding: 0;
-      }
-
-      body {
         width: 100vw;
         height: 100vh;
       }
-
-      iframe {
-        overflow: hidden;
-        border: 0;
-        height: 100%;
+      #metapage-container {
         width: 100%;
+        height: 100%;
       }
     </style>
   </head>
-
   <body>
-    <div style="width: 100%; height: 100%" id="metapage-container"></div>
+    <div id="metapage-container"></div>
 
     <script type="module">
-      // the only function you need to import to render a metapage
-      import { renderMetapage } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.8.15";
+      import { renderMetapage } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.8.35";
 
-      // download a metapage definition from metapage.io
-      // or just use your own definition JSON
-      const response = await fetch(
+      const definition = await fetch(
         "https://metapage.io/m/87ae11673508447e883b598bf7da9c5d/metapage.json",
-      );
-      const metapageDefinition = await response.json();
-
-      // handle metapage outputs
-      const onOutputs = (outputs) => {
-        // do something with the outputs
-        console.log("outputs", outputs);
-      };
-      // set input values with the provided setInputs function
-      // dispose removes all event listeners and unloads the metapage
-      const { setInputs, dispose } = await renderMetapage({
-        definition: metapageDefinition,
-        onOutputs,
+      ).then((r) => r.json());
+
+      const { setInputs, dispose, metapage } = await renderMetapage({
+        definition,
         rootDiv: document.getElementById("metapage-container"),
+        onOutputs: (outputs) => {
+          console.log("Metaframe outputs:", outputs);
+        },
         options: {
-          hideBorder: true,
           hideFrameBorders: true,
           hideOptions: true,
-          hideMetaframeLabels: true,
         },
       });
+
+      // Send inputs to metaframes
+      setInputs({
+        metaframeId: {
+          inputPipeName: "some value",
+        },
+      });
+
+      // Clean up when done
+      // dispose();
+    </script>
+  </body>
+</html>
+```
+
+### Building a Metaframe Component
+
+```javascript
+import { Metaframe } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.8.35";
+
+const metaframe = new Metaframe();
+
+// Handle inputs
+metaframe.onInputs((inputs) => {
+  const { data, config } = inputs;
+
+  // Process inputs
+  const result = processData(data, config);
+
+  // Send outputs
+  metaframe.setOutputs({
+    result: result,
+    timestamp: Date.now(),
+  });
+});
+
+// Individual input listener
+metaframe.onInput("reset", () => {
+  metaframe.setOutputs({});
+});
+
+// Get a specific input value
+const currentValue = metaframe.getInput("data");
+
+// Get all inputs
+const allInputs = metaframe.getInputs();
+
+// Clean up
+metaframe.dispose();
+```
+
+### Programmatic Metapage Control
+
+```javascript
+import { Metapage } from "@metapages/metapage";
+
+const metapage = new Metapage({
+  definition: {
+    version: "2",
+    metaframes: {
+      viewer: {
+        url: "https://markdown.mtfm.io/",
+      },
+    },
+  },
+});
+
+// Listen to metaframe outputs
+metapage.on(Metapage.OUTPUTS, (outputs) => {
+  console.log("Outputs from all metaframes:", outputs);
+});
+
+// Set inputs to metaframes
+await metapage.setInputs({
+  viewer: {
+    text: "# Hello World",
+  },
+});
+
+// Get current outputs
+const outputs = metapage.getState().metaframes.outputs;
+
+// Clean up
+metapage.dispose();
+```
+
+## Advanced Features
+
+### Hash Parameters in Metaframes
+
+Metaframes can read and write to their URL hash parameters:
+
+```javascript
+import {
+  getHashParamValueJsonFromWindow,
+  setHashParamValueJsonInWindow,
+} from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.8.35";
+
+// Read from URL hash
+const config = getHashParamValueJsonFromWindow("config");
+
+// Write to URL hash
+setHashParamValueJsonInWindow("config", { theme: "dark" });
+```
+
+### Pattern Matching in Pipes
+
+Use glob patterns to match multiple outputs:
+
+```javascript
+{
+  "inputs": [
+    {
+      "metaframe": "source",
+      "source": "data/*",     // Matches data/foo, data/bar, etc.
+      "target": "inputs/"
+    }
+  ]
+}
+```
+
+### Binary Data Handling
+
+```javascript
+// Send binary data
+const imageData = await fetch("/image.png").then((r) => r.arrayBuffer());
+metaframe.setOutput("image", imageData);
+
+// Receive and use
+metaframe.onInput("image", async (data) => {
+  const blob = new Blob([data]);
+  const url = URL.createObjectURL(blob);
+  document.getElementById("img").src = url;
+});
+```
+
+## API Overview
+
+### renderMetapage(options)
+
+Render a metapage into a DOM element.
+
+**Parameters:**
+
+- `definition`: Metapage definition object
+- `rootDiv`: DOM element to render into
+- `onOutputs`: Callback for metaframe outputs (optional)
+- `options`: Rendering options (optional)
+  - `hideBorder`: Hide metapage border
+  - `hideFrameBorders`: Hide individual metaframe borders
+  - `hideOptions`: Hide options panel
+  - `hideMetaframeLabels`: Hide metaframe labels
+
+**Returns:** `{ setInputs, setOutputs, dispose, metapage }`
+
+### Metapage Class
+
+**Methods:**
+
+- `setInputs(inputs)`: Set inputs for metaframes
+- `getState()`: Get current state (inputs/outputs)
+- `dispose()`: Clean up and remove all listeners
+- `on(event, handler)`: Listen to events
+
+**Events:**
+
+- `Metapage.OUTPUTS`: When metaframe outputs change
+- `Metapage.INPUTS`: When metapage inputs change
+- `Metapage.DEFINITION`: When definition changes
+
+### Metaframe Class
+
+**Methods:**
+
+- `setOutput(name, value)`: Set a single output
+- `setOutputs(outputs)`: Set multiple outputs
+- `getInput(name)`: Get a single input value
+- `getInputs()`: Get all input values
+- `onInput(name, callback)`: Listen to specific input
+- `onInputs(callback)`: Listen to all inputs
+- `dispose()`: Clean up
+
+**Properties:**
+
+- `id`: Metaframe ID assigned by parent metapage
+- `isInputOutputBlobSerialization`: Enable/disable automatic binary serialization
+
+## Creating Your Own Metaframes
+
+Any web application can become a metaframe by:
+
+1. Loading the library
+2. Creating a `Metaframe` instance
+3. Listening for inputs
+4. Sending outputs
+
+Example minimal metaframe:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>My Metaframe</title>
+  </head>
+  <body>
+    <script type="module">
+      import { Metaframe } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.8.35";
+
+      const metaframe = new Metaframe();
+
+      metaframe.onInputs((inputs) => {
+        // Your logic here
+        metaframe.setOutput("result", "processed: " + JSON.stringify(inputs));
+      });
     </script>
   </body>
 </html>
 ```
 
-Online tests and conversion tools: [https://module.metapage.io](https://module.metapage.io)
+## TypeScript Support
+
+Full TypeScript definitions are included:
+
+```typescript
+import {
+  Metapage,
+  Metaframe,
+  MetapageDefinitionV2,
+  MetaframeInputMap,
+  MetapageInstanceInputs,
+} from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.8.35";
+
+const definition: MetapageDefinitionV2 = {
+  version: "2",
+  metaframes: {
+    example: {
+      url: "https://example.com",
+    },
+  },
+};
+
+const metapage = new Metapage({ definition });
+```
+
+## Browser Support
+
+- Chrome 78+
+- Modern browsers with ES2020 support
+- ES modules required
+
+## License
+
+Apache-2.0
+
+## Contributing
+
+Issues and pull requests welcome at [https://github.com/metapages/metapage](https://github.com/metapages/metapage)
+
+## More Resources
+
+- [Documentation](https://docs.metapage.io)
+- [Examples Gallery](https://metapage.io)
+- [Create Metaframes](https://js.mtfm.io)
+- [Community](https://github.com/metapages/metapage/discussions)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@metapages/metapage",
   "public": true,
-  "version": "1.8.29",
+  "version": "1.9.0",
   "description": "Connect web pages together",
   "repository": "https://github.com/metapages/metapage",
   "homepage": "https://metapage.io/",
@@ -39,6 +39,7 @@
     "@vitest/browser": "^3.2.4",
     "playwright": "^1.54.2",
     "rollup-plugin-typescript-paths": "^1.4.0",
+    "tslib": "^2.6.2",
     "typescript": "^5.3.3",
     "vite": "^4.4.11",
     "vitest": "^3.2.4"

package/src/metapage/MetapageIFrameRpcClient.ts

@@ -1,7 +1,18 @@
 import { EventEmitter, ListenerFn } from "eventemitter3";
 
+import { getHashParamValueJsonFromUrl } from "@metapages/hash-query";
+
 import { VERSION_METAPAGE } from "./Constants";
+import { convertMetaframeJsonToCurrentVersion } from "./conversions-metaframe";
+import { Disposer, MetaframeId, MetaframePipeId, MetapageId } from "./core";
 import { serializeInputs } from "./data";
+import { MetapageEvents } from "./events";
+import {
+  ClientMessageRecievedAck,
+  JsonRpcMethodsFromParent,
+  MinimumClientMessage,
+  SetupIframeServerResponseData,
+} from "./jsonrpc";
 import { JsonRpcRequest } from "./jsonrpc2";
 import {
   log as MetapageToolsLog,
@@ -10,20 +21,10 @@ import {
   stringToRgb,
 } from "./MetapageTools";
 import { MetapageHashParams, MetapageShared } from "./Shared";
-import { MetaframeDefinitionV2 } from "./v2";
+import { getMetaframeDefinitionFromUrl } from "./util";
 import { MetaframeInputMap, MetapageInstanceInputs } from "./v0_4";
-import { Disposer, MetaframeId, MetaframePipeId, MetapageId } from "./core";
-import { convertMetaframeJsonToCurrentVersion } from "./conversions-metaframe";
-import { MetapageEvents } from "./events";
-import {
-  ClientMessageRecievedAck,
-  JsonRpcMethodsFromParent,
-  MinimumClientMessage,
-  SetupIframeServerResponseData,
-} from "./jsonrpc";
+import { MetaframeDefinitionV2 } from "./v2";
 import { VersionsMetaframe, VersionsMetapage } from "./versions";
-import { getHashParamValueJsonFromUrl } from "@metapages/hash-query";
-import { getMetaframeDefinitionFromUrl } from "./util";
 
 /**
  * This class runs in the parent metapage, and connects the communication pipes
@@ -326,7 +327,7 @@ export class MetapageIFrameRpcClient extends EventEmitter<
 
     if (this._metapage.listenerCount(MetapageEvents.Outputs) > 0) {
       var outputsUpdate: MetapageInstanceInputs = {};
-      outputsUpdate[this.id] = this.outputs;
+      outputsUpdate[this.id] = maybeNewOutputs;
       this._metapage.emit(MetapageEvents.Outputs, outputsUpdate);
     }
   }

package/src/metapage/conversions-metaframe.ts

@@ -9,10 +9,34 @@ import {
 } from "./v0_4/index.js";
 import { MetaframeDefinitionV1 } from "./v1/index.js";
 import { MetaframeVersionCurrent, type VersionsMetaframe } from "./versions.js";
-import { MetaframeDefinitionV2 } from "./v2/metaframe.js";
+import {
+  HashParamsObject,
+  HashParamsRaw,
+  MetaframeDefinitionV2,
+} from "./v2/metaframe.js";
 
 const fetchRetry = fetchRetryWrapper(fetch);
 
+/**
+ * Normalizes hashParams from legacy array format to object format.
+ * - Array format ["foo", "bar"] becomes { foo: {}, bar: {} }
+ * - Object format is passed through unchanged
+ * - undefined/null returns undefined
+ */
+export const normalizeHashParams = (
+  hashParams: HashParamsRaw | undefined,
+): HashParamsObject | undefined => {
+  if (!hashParams) return undefined;
+  if (Array.isArray(hashParams)) {
+    const result: HashParamsObject = {};
+    for (const key of hashParams) {
+      result[key] = {};
+    }
+    return result;
+  }
+  return hashParams;
+};
+
 type AnyMetaframeDefinition =
   | MetaframeDefinitionV03
   | MetaframeDefinitionV4
@@ -70,7 +94,7 @@ export const convertMetaframeDefinitionToVersion = async (
 
 export const convertMetaframeDefinitionToCurrentVersion = async (
   def: any | AnyMetaframeDefinition,
-): Promise<MetaframeDefinitionV1> => {
+): Promise<MetaframeDefinitionV2> => {
   return convertMetaframeDefinitionToVersion(def, MetaframeVersionCurrent);
 };
 
@@ -213,7 +237,12 @@ export const convertMetaframeJsonToCurrentVersion = async (
   if (!m) {
     return;
   }
-  return convertMetaframeDefinitionToCurrentVersion(m);
+  const converted = await convertMetaframeDefinitionToCurrentVersion(m);
+  // Normalize hashParams from array format to object format
+  if (converted?.hashParams) {
+    converted.hashParams = normalizeHashParams(converted.hashParams);
+  }
+  return converted;
 };
 
 const definition_v0_4_to_v0_3 = (def: MetaframeDefinitionV4) => {

package/src/metapage/v2/metaframe.ts

@@ -2,6 +2,31 @@ import { VersionsMetaframe } from "../versions.js";
 import { MetaframePipeDefinition } from "../v0_4/index.js";
 import { MetaframeOperationsV1 } from "../v1/metaframe.js";
 
+// Hash parameter types
+export type HashParamType =
+  | "string"
+  | "stringBase64"
+  | "boolean"
+  | "json"
+  | "File|Blob"
+  | "number";
+
+export interface HashParamDefinition {
+  type?: HashParamType;
+  description?: string; // For humans or LLMs
+  label?: string; // Short label
+  value?: any; // Default value
+  allowedValues?: any[]; // Allowed values
+  defaultValue?: any; // Default value
+}
+
+export type HashParamsObject = {
+  [key: string]: HashParamDefinition;
+};
+
+// Union type for raw definitions (before normalization)
+export type HashParamsRaw = string[] | HashParamsObject;
+
 export type MetaframeMetadataV2 = {
   name?: string;
   description?: string;
@@ -27,6 +52,8 @@ export interface MetaframeDefinitionV2 {
   // Set or override allowed features for the iframe
   // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#sandbox
   sandbox?: string;
-  // whitelist allowed hash parameters.
-  hashParams?: string[];
+  // Hash parameters configuration.
+  // Accepts both legacy array format (string[]) and new object format (HashParamsObject).
+  // When fetched via helper methods, array format is normalized to object format.
+  hashParams?: HashParamsRaw;
 }