@metapages/metapage 1.10.1 → 1.10.2

package/README.md

@@ -36,7 +36,7 @@ import {
   renderMetapage,
   Metapage,
   Metaframe,
-} from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.1";
+} from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.2";
 ```
 
 ## Quick Start
@@ -82,7 +82,7 @@ The `renderMetapage` function the `react-grid-layout` layout in `metapage.json`:
 If you're building a component to use in a metapage:
 
 ```javascript
-import { Metaframe } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.1";
+import { Metaframe } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.2";
 
 const metaframe = new Metaframe();
 
@@ -223,7 +223,7 @@ metaframe.onInput("file", (file) => {
     <div id="metapage-container"></div>
 
     <script type="module">
-      import { renderMetapage } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.1";
+      import { renderMetapage } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.2";
 
       const definition = await fetch(
         "https://metapage.io/m/87ae11673508447e883b598bf7da9c5d/metapage.json",
@@ -258,7 +258,7 @@ metaframe.onInput("file", (file) => {
 ### Building a Metaframe Component
 
 ```javascript
-import { Metaframe } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.1";
+import { Metaframe } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.2";
 
 const metaframe = new Metaframe();
 
@@ -335,7 +335,7 @@ Metaframes can read and write to their URL hash parameters:
 import {
   getHashParamValueJsonFromWindow,
   setHashParamValueJsonInWindow,
-} from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.1";
+} from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.2";
 
 // Read from URL hash
 const config = getHashParamValueJsonFromWindow("config");
@@ -375,6 +375,177 @@ metaframe.onInput("image", async (data) => {
 });
 ```
 
+## Secrets
+
+Inject sensitive credentials (API keys, tokens, etc.) into metaframe URLs at runtime while ensuring they are never exposed when retrieving the metapage definition.
+
+### API
+
+```typescript
+import { Metapage, InjectSecretsPayload } from "@metapages/metapage";
+
+const metapage = new Metapage();
+await metapage.setDefinition(definition);
+
+const secrets: InjectSecretsPayload = {
+  frameSecrets: {
+    myMetaframe: {
+      hashParams: {
+        apiKey: "sk-abc123",
+        token: "secret-token",
+      },
+      queryParams: {
+        auth: "bearer-token",
+      },
+    },
+  },
+};
+
+metapage.injectSecrets(secrets);
+```
+
+### Type Definition
+
+```typescript
+type InjectSecretsPayload = {
+  frameSecrets: {
+    [metaframeName: string]: {
+      hashParams?: { [name: string]: string };
+      queryParams?: { [name: string]: string };
+    };
+  };
+};
+```
+
+### Behavior
+
+- **Injection**: Secrets are base64-encoded into metaframe URL hash/query parameters using `setHashParamValueBase64EncodedInUrl` from `@metapages/hash-query`
+- **Accumulation**: Multiple calls to `injectSecrets()` accumulate secrets rather than replacing previous ones
+- **Safe removal**: `getDefinition()` and definition change events automatically strip secrets, restoring original parameter values
+- **Persistence across updates**: Secrets survive `setDefinition()` calls — if a metaframe still exists in the new definition, its secrets are re-injected
+- **Cleanup**: Secrets are removed when metaframes are removed via `removeMetaframe()` or `removeAll()`
+
+### Example
+
+```typescript
+const metapage = new Metapage();
+await metapage.setDefinition(definition);
+
+// Inject a secret
+metapage.injectSecrets({
+  frameSecrets: {
+    secret1test: {
+      hashParams: {
+        secret1: "injected secret",
+      },
+    },
+  },
+});
+
+// The metaframe iframe URL now contains the secret (base64-encoded in hash)
+// But getDefinition() returns the original URL without secrets:
+const def = metapage.getDefinition();
+// def.metaframes.secret1test.url has NO secret params
+
+// Definition events also exclude secrets:
+metapage.on(Metapage.DEFINITION, (cleanDef) => {
+  // cleanDef has no secrets
+});
+```
+
+### Security Notes
+
+- Secrets are base64-encoded (not encrypted) in URLs
+- Metaframe iframes receive secrets via their URL hash/query params at runtime
+- Secrets are stripped from all definition retrieval methods and events
+- Secret storage is cleared on `dispose()`
+
+## updateDefinition
+
+`updateDefinition` is the preferred way to change the metapage definition at runtime when you need to react to what changed. Unlike `setDefinition`, it:
+
+- Always emits a `DefinitionUpdate` event — even on the very first call
+- Includes a structured diff of which metaframes were added and removed
+- Automatically emits a `State` event when metaframes are added or removed
+
+### API
+
+```typescript
+await metapage.updateDefinition(definition, state?);
+```
+
+| Parameter    | Type                       | Description                                            |
+| ------------ | -------------------------- | ------------------------------------------------------ |
+| `definition` | `MetapageDefinition`       | The new metapage definition                            |
+| `state`      | `MetapageState` (optional) | Initial state to apply alongside the definition update |
+
+### Event Payload
+
+Listen with `Metapage.DEFINITION_UPDATE`. The event payload has this shape:
+
+```typescript
+interface MetapageEventDefinitionUpdate {
+  definition: MetapageDefinition; // current definition (secrets stripped)
+  metaframes: {
+    current: { [id: string]: MetapageIFrameRpcClient }; // all metaframes after update
+    added: { [id: string]: MetapageIFrameRpcClient }; // metaframes that were added
+    removed: { [id: string]: MetapageIFrameRpcClient }; // metaframes that were removed (disposed)
+  };
+}
+```
+
+### Example
+
+```typescript
+import { Metapage, MetapageEventDefinitionUpdate } from "@metapages/metapage";
+
+const metapage = new Metapage();
+
+metapage.on(
+  Metapage.DEFINITION_UPDATE,
+  (event: MetapageEventDefinitionUpdate) => {
+    const { added, removed, current } = event.metaframes;
+
+    console.log("Current metaframes:", Object.keys(current));
+    console.log("Added:", Object.keys(added));
+    console.log("Removed:", Object.keys(removed));
+  },
+);
+
+// First call — fires immediately (unlike setDefinition)
+await metapage.updateDefinition({
+  metaframes: {
+    viewer: { url: "https://markdown.mtfm.io/" },
+  },
+});
+
+// Second call — event reports frame2 in `added`
+await metapage.updateDefinition({
+  metaframes: {
+    viewer: { url: "https://markdown.mtfm.io/" },
+    editor: { url: "https://editor.mtfm.io/" },
+  },
+});
+```
+
+### Comparison with setDefinition
+
+| Behaviour                     | `setDefinition` | `updateDefinition` |
+| ----------------------------- | --------------- | ------------------ |
+| Emits event on first call     | No              | Yes                |
+| Event type                    | `Definition`    | `DefinitionUpdate` |
+| Diff of added/removed frames  | No              | Yes                |
+| Emits `State` on frame change | No              | Yes                |
+
+### State event
+
+`State` is automatically emitted (to any listeners) when:
+
+- Metaframes are added or removed, OR
+- An explicit `state` argument is passed and is non-empty
+
+---
+
 ## API Overview
 
 ### renderMetapage(options)
@@ -398,8 +569,11 @@ Render a metapage into a DOM element.
 
 **Methods:**
 
+- `setDefinition(def, state?)`: Set the metapage definition; emits `Definition` on subsequent calls only
+- `updateDefinition(def, state?)`: Set the definition and always emit `DefinitionUpdate` with added/removed diff (see [updateDefinition](#updatedefinition))
 - `setInputs(inputs)`: Set inputs for metaframes
 - `getState()`: Get current state (inputs/outputs)
+- `injectSecrets(secrets)`: Inject secrets into metaframe URLs (see [Secrets](#secrets))
 - `dispose()`: Clean up and remove all listeners
 - `on(event, handler)`: Listen to events
 
@@ -407,7 +581,9 @@ Render a metapage into a DOM element.
 
 - `Metapage.OUTPUTS`: When metaframe outputs change
 - `Metapage.INPUTS`: When metapage inputs change
-- `Metapage.DEFINITION`: When definition changes
+- `Metapage.DEFINITION`: When definition changes (not emitted on first `setDefinition` call)
+- `Metapage.DEFINITION_UPDATE`: When `updateDefinition` is called; payload includes added/removed metaframe diff (see [updateDefinition](#updatedefinition))
+- `Metapage.STATE`: When metapage state changes
 
 ### Metaframe Class
 
@@ -445,7 +621,7 @@ Example minimal metaframe:
   </head>
   <body>
     <script type="module">
-      import { Metaframe } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.1";
+      import { Metaframe } from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.2";
 
       const metaframe = new Metaframe();
 
@@ -466,13 +642,12 @@ Full TypeScript definitions are included:
 import {
   Metapage,
   Metaframe,
-  MetapageDefinitionV2,
+  MetapageDefinition,
   MetaframeInputMap,
   MetapageInstanceInputs,
-} from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.1";
+} from "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.2";
 
-const definition: MetapageDefinitionV2 = {
-  version: "2",
+const definition: MetapageDefinition = {
   metaframes: {
     example: {
       url: "https://example.com",