framejs 0.4.0__tar.gz

framejs-0.4.0/.gitignore

@@ -0,0 +1,3 @@
+dist/
+*.egg-info/
+__pycache__/

framejs-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Metapages
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

framejs-0.4.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: framejs
+Version: 0.4.0
+Summary: Embed framejs frames as interactive widgets in Jupyter and marimo notebooks
+Project-URL: Homepage, https://framejs.io/docs/integrations/jupyter
+Project-URL: Repository, https://github.com/metapages/framejs.io
+Project-URL: Issues, https://github.com/metapages/framejs.io/issues
+Project-URL: Changelog, https://github.com/metapages/framejs.io/blob/main/python/README.md
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Jupyter
+Classifier: Framework :: Jupyter :: JupyterLab
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.8
+Requires-Dist: anywidget>=0.9.0
+Requires-Dist: traitlets>=5.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: jupyter
+Requires-Dist: jupyterlab; extra == 'jupyter'
+Provides-Extra: marimo
+Requires-Dist: marimo; extra == 'marimo'
+Description-Content-Type: text/markdown
+
+# framejs
+
+An [anywidget](https://anywidget.dev/) for embedding [framejs](https://framejs.io/docs)
+frames (and [metapage](https://docs.metapage.io/) URLs) in Jupyter and marimo
+notebooks.
+
+> **Renamed in 0.4.0.** This package was published as `metaframe-widget`, and the
+> class as `MetaframeWidget`. Both names still work — `metaframe-widget` now
+> installs this package, and `MetaframeWidget` is an alias of `Frame` — but new
+> code should use `framejs` and `Frame`.
+
+## Install
+
+```bash
+pip install framejs
+```
+
+With environment extras:
+
+```bash
+pip install "framejs[jupyter]"   # includes jupyterlab
+pip install "framejs[marimo]"    # includes marimo
+```
+
+## Quick start
+
+### Jupyter
+
+```python
+from framejs import Frame
+
+w = Frame(url="https://framejs.io/#?js=...", height="300px")
+w
+```
+
+### marimo
+
+```python
+import marimo as mo
+from framejs import Frame
+
+w = Frame(url="https://framejs.io/#?js=...", height="300px")
+mo.ui.anywidget(w)
+```
+
+A widget is always created from a URL. To embed your own code, build and save it
+at [framejs.io](https://framejs.io/) — the editor mints a short URL you can paste
+into `url=`. The URL is the portable, saveable form of a frame; the code itself
+lives behind it rather than being inlined in your notebook.
+
+### URL forms
+
+Any of these work as `url=`:
+
+```python
+# Raw / full URL — the code is inlined in the hash (can get very long)
+Frame(url="https://framejs.io/#?js=...")
+
+# Expiring snapshot — content-addressed, kept ~30 days, then garbage-collected
+# (editor: "Create expiring snapshot")
+Frame(url="https://framejs.io/j/<sha256>")
+
+# Durable, editable frame — permanent, tied to your account (editor: "Save")
+# Paste either host: a framejs.app/j/<uuid> URL is loaded from framejs.io, the
+# runtime that serves frames with CORS headers (a notebook cannot load the
+# framejs.app one directly). `w.url` still reads back what you passed.
+Frame(url="https://framejs.app/j/<uuid>")
+```
+
+Prefer the durable `/j/<uuid>` form in notebooks you keep. See
+[Short URLs](https://framejs.io/docs/guide/short-urls) for the full comparison.
+
+## API reference
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | `str` | `""` | Full frame URL (including hash params) |
+| `inputs` | `dict` | `{}` | Dict of inputs to push to the frame |
+| `outputs` | `dict` | `{}` | Dict of outputs received from the frame (read-only) |
+| `width` | `str` | `"100%"` | CSS width for the widget container |
+| `height` | `str` | `"400px"` | CSS height for the widget container |
+| `allow` | `str` | `""` | iframe `allow` attribute (e.g. `"camera; microphone"`) |
+
+### Methods
+
+- **`set_inputs(d)`** — merge a dict into current inputs
+- **`set_input(key, value)`** — set a single input key
+- **`on_outputs_change(callback)`** — register a callback for output changes
+- **`on_saved_url_change(callback)`** — register a callback for when the user creates an expiring snapshot (`/j/<sha256>`) inside the widget
+- **`pipe_to(target, output_key, input_key=None)`** — connect an output to another widget's input
+
+## Piping widgets
+
+```python
+source = Frame(url="...")
+sink = Frame(url="...")
+source.pipe_to(sink, output_key="result", input_key="data")
+```
+
+## No anywidget? Use a plain iframe
+
+To send data **into** a frame and nothing more, you need no package at all —
+encode the inputs into the URL and show it with `IPython.display.IFrame`. See
+[the Jupyter guide](https://framejs.io/docs/integrations/jupyter#without-anywidget-a-plain-iframe).
+
+## Links
+
+- [GitHub](https://github.com/metapages/framejs.io)
+- [Jupyter examples](https://github.com/metapages/framejs.io/tree/main/examples/jupyter)
+- [marimo examples](https://github.com/metapages/framejs.io/tree/main/examples/marimo)

framejs-0.4.0/README.md

@@ -0,0 +1,110 @@
+# framejs
+
+An [anywidget](https://anywidget.dev/) for embedding [framejs](https://framejs.io/docs)
+frames (and [metapage](https://docs.metapage.io/) URLs) in Jupyter and marimo
+notebooks.
+
+> **Renamed in 0.4.0.** This package was published as `metaframe-widget`, and the
+> class as `MetaframeWidget`. Both names still work — `metaframe-widget` now
+> installs this package, and `MetaframeWidget` is an alias of `Frame` — but new
+> code should use `framejs` and `Frame`.
+
+## Install
+
+```bash
+pip install framejs
+```
+
+With environment extras:
+
+```bash
+pip install "framejs[jupyter]"   # includes jupyterlab
+pip install "framejs[marimo]"    # includes marimo
+```
+
+## Quick start
+
+### Jupyter
+
+```python
+from framejs import Frame
+
+w = Frame(url="https://framejs.io/#?js=...", height="300px")
+w
+```
+
+### marimo
+
+```python
+import marimo as mo
+from framejs import Frame
+
+w = Frame(url="https://framejs.io/#?js=...", height="300px")
+mo.ui.anywidget(w)
+```
+
+A widget is always created from a URL. To embed your own code, build and save it
+at [framejs.io](https://framejs.io/) — the editor mints a short URL you can paste
+into `url=`. The URL is the portable, saveable form of a frame; the code itself
+lives behind it rather than being inlined in your notebook.
+
+### URL forms
+
+Any of these work as `url=`:
+
+```python
+# Raw / full URL — the code is inlined in the hash (can get very long)
+Frame(url="https://framejs.io/#?js=...")
+
+# Expiring snapshot — content-addressed, kept ~30 days, then garbage-collected
+# (editor: "Create expiring snapshot")
+Frame(url="https://framejs.io/j/<sha256>")
+
+# Durable, editable frame — permanent, tied to your account (editor: "Save")
+# Paste either host: a framejs.app/j/<uuid> URL is loaded from framejs.io, the
+# runtime that serves frames with CORS headers (a notebook cannot load the
+# framejs.app one directly). `w.url` still reads back what you passed.
+Frame(url="https://framejs.app/j/<uuid>")
+```
+
+Prefer the durable `/j/<uuid>` form in notebooks you keep. See
+[Short URLs](https://framejs.io/docs/guide/short-urls) for the full comparison.
+
+## API reference
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | `str` | `""` | Full frame URL (including hash params) |
+| `inputs` | `dict` | `{}` | Dict of inputs to push to the frame |
+| `outputs` | `dict` | `{}` | Dict of outputs received from the frame (read-only) |
+| `width` | `str` | `"100%"` | CSS width for the widget container |
+| `height` | `str` | `"400px"` | CSS height for the widget container |
+| `allow` | `str` | `""` | iframe `allow` attribute (e.g. `"camera; microphone"`) |
+
+### Methods
+
+- **`set_inputs(d)`** — merge a dict into current inputs
+- **`set_input(key, value)`** — set a single input key
+- **`on_outputs_change(callback)`** — register a callback for output changes
+- **`on_saved_url_change(callback)`** — register a callback for when the user creates an expiring snapshot (`/j/<sha256>`) inside the widget
+- **`pipe_to(target, output_key, input_key=None)`** — connect an output to another widget's input
+
+## Piping widgets
+
+```python
+source = Frame(url="...")
+sink = Frame(url="...")
+source.pipe_to(sink, output_key="result", input_key="data")
+```
+
+## No anywidget? Use a plain iframe
+
+To send data **into** a frame and nothing more, you need no package at all —
+encode the inputs into the URL and show it with `IPython.display.IFrame`. See
+[the Jupyter guide](https://framejs.io/docs/integrations/jupyter#without-anywidget-a-plain-iframe).
+
+## Links
+
+- [GitHub](https://github.com/metapages/framejs.io)
+- [Jupyter examples](https://github.com/metapages/framejs.io/tree/main/examples/jupyter)
+- [marimo examples](https://github.com/metapages/framejs.io/tree/main/examples/marimo)

framejs-0.4.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "framejs"
+version = "0.4.0"
+description = "Embed framejs frames as interactive widgets in Jupyter and marimo notebooks"
+license = "MIT"
+requires-python = ">=3.8"
+readme = "README.md"
+dependencies = [
+    "anywidget>=0.9.0",
+    "traitlets>=5.0.0",
+]
+classifiers = [
+    "Framework :: Jupyter",
+    "Framework :: Jupyter :: JupyterLab",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+]
+
+[project.urls]
+Homepage = "https://framejs.io/docs/integrations/jupyter"
+Repository = "https://github.com/metapages/framejs.io"
+Issues = "https://github.com/metapages/framejs.io/issues"
+Changelog = "https://github.com/metapages/framejs.io/blob/main/python/README.md"
+
+[project.optional-dependencies]
+jupyter = ["jupyterlab"]
+marimo = ["marimo"]
+dev = ["pytest"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/framejs"]

framejs-0.4.0/src/framejs/__init__.py

@@ -0,0 +1,3 @@
+from ._widget import Frame, MetaframeWidget, runtime_url
+
+__all__ = ["Frame", "MetaframeWidget", "runtime_url"]

framejs-0.4.0/src/framejs/_esm.py

@@ -0,0 +1,208 @@
+ESM = """
+const CDN_URL = "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.14/+esm";
+
+let _renderMetapage = null;
+
+async function loadRenderMetapage() {
+    if (!_renderMetapage) {
+        const mod = await import(CDN_URL);
+        _renderMetapage = mod.renderMetapage;
+    }
+    return _renderMetapage;
+}
+
+export default {
+    async render({ model, el }) {
+        // el's own `display` is managed by the notebook host — JupyterLab's
+        // ipywidgets layer resets el.style.display to "block" AFTER render, which
+        // silently kills a flex column set directly on el (that's why the widget
+        // renders full-height standalone but collapses to ~40px in a notebook).
+        // So we don't lay out el itself; we only give it a definite size, then own
+        // an inner `root` wrapper. root's height:100% resolves against el's definite
+        // height regardless of el's display, and root's flex column (which the host
+        // never touches) lets the metapage fill the space with an optional
+        // "saved URL" footer beneath it.
+        el.style.boxSizing = "border-box";
+        el.style.width = model.get("width") || "100%";
+        el.style.height = model.get("height") || "400px";
+
+        const root = document.createElement("div");
+        root.style.cssText = "display: flex; flex-direction: column; width: 100%; height: 100%; box-sizing: border-box;";
+        el.appendChild(root);
+
+        // Inject CSS to remove iframe borders and inline gaps
+        const style = document.createElement("style");
+        // renderMetapage lays the metaframe out in a react-grid-layout grid and
+        // stamps an inline `min-height` floor on the grid container (default h=3 *
+        // rowHeight 100 + margins => 350px) and on the item wrapper (300px). The
+        // grid rows are `1fr`, so nothing else pins the size — only those floors.
+        // When the widget's height is set below 350px, the floor wins and the
+        // content is cut off at 350px. Override the floors so the metaframe fills
+        // our explicit height at any size (large heights already fill via 1fr).
+        style.textContent = ".framejs-frame-container { box-sizing: border-box; flex: 1 1 auto; min-height: 0; width: 100%; } .framejs-frame-container * { box-sizing: border-box; min-height: 0 !important; } .framejs-frame-container > div { height: 100%; } .framejs-frame-container iframe { border: none; display: block; margin: 0; padding: 0; box-sizing: border-box; width: 100%; height: 100%; }";
+        root.appendChild(style);
+
+        const container = document.createElement("div");
+        container.className = "framejs-frame-container metaframe-widget-container";
+        root.appendChild(container);
+
+        // Footer showing the latest short URL produced by editing + saving.
+        const footer = document.createElement("div");
+        footer.style.cssText = "flex: 0 0 auto; display: none; align-items: center; gap: 6px; padding: 4px 6px; font-family: sans-serif; font-size: 12px; color: #555; background: #f7f7f7; border-top: 1px solid #e0e0e0; overflow: hidden;";
+        const footerLabel = document.createElement("span");
+        footerLabel.textContent = "Saved:";
+        footerLabel.style.flex = "0 0 auto";
+        const footerLink = document.createElement("a");
+        footerLink.target = "_blank";
+        footerLink.rel = "noopener noreferrer";
+        footerLink.style.cssText = "flex: 1 1 auto; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;";
+        const footerCopy = document.createElement("button");
+        footerCopy.textContent = "copy";
+        footerCopy.style.cssText = "flex: 0 0 auto; cursor: pointer; font-size: 11px; padding: 1px 6px;";
+        footer.appendChild(footerLabel);
+        footer.appendChild(footerLink);
+        footer.appendChild(footerCopy);
+        root.appendChild(footer);
+
+        function renderSavedUrl() {
+            const savedUrl = model.get("saved_url") || "";
+            if (savedUrl) {
+                footerLink.textContent = savedUrl;
+                footerLink.href = savedUrl;
+                footer.style.display = "flex";
+            } else {
+                footer.style.display = "none";
+            }
+        }
+        footerCopy.addEventListener("click", () => {
+            const savedUrl = model.get("saved_url") || "";
+            if (savedUrl && navigator.clipboard) {
+                navigator.clipboard.writeText(savedUrl);
+            }
+        });
+        renderSavedUrl();
+
+        const renderMetapage = await loadRenderMetapage();
+
+        let currentResult = null;
+
+        function applyAllowToIframes() {
+            const allow = model.get("allow") || "";
+            if (allow) {
+                container.querySelectorAll("iframe").forEach(iframe => {
+                    iframe.allow = allow;
+                });
+            }
+        }
+
+        async function createMetapage() {
+            if (currentResult) {
+                currentResult.dispose();
+                currentResult = null;
+            }
+            container.innerHTML = "";
+
+            // The runtime URL, not the one the user typed -- see runtime_url()
+            // in _widget.py. Falls back to `url` so an empty trait is harmless.
+            const url = model.get("_runtime_url") || model.get("url");
+            if (!url) return;
+
+            const definition = {
+                version: "0.3",
+                metaframes: {
+                    mf: { url },
+                },
+            };
+
+            const result = await renderMetapage({
+                definition,
+                rootDiv: container,
+                onOutputs: (outputs) => {
+                    const mfOutputs = outputs.mf || {};
+                    model.set("outputs", JSON.parse(JSON.stringify(mfOutputs)));
+                    model.save_changes();
+                },
+            });
+            currentResult = result;
+
+            applyAllowToIframes();
+
+            // Push current inputs if any
+            const inputs = model.get("inputs");
+            if (inputs && Object.keys(inputs).length > 0) {
+                result.setInputs({ mf: inputs });
+            }
+        }
+
+        // NOTE: the message `type` below is a WIRE PROTOCOL string shared with the
+        // framejs editor (editor/src/.../ButtonShortenUrl.tsx). It is deliberately
+        // NOT renamed with the package: the editor is deployed once and talks to
+        // every installed version of this package, including releases that predate
+        // the framejs rename, so changing it here would make old installs stop
+        // receiving snapshot URLs.
+        //
+        // The embedded editor (same-origin to the URL-shortening worker) mints an
+        // expiring /j/<sha256> snapshot when the user clicks "Create expiring
+        // snapshot", then postMessages it here. We record it in `saved_url`
+        // WITHOUT touching `url`, so the live iframe the user is editing is never
+        // torn down and reloaded.
+        function expectedOrigin() {
+            try {
+                // Must be the URL the iframe actually loaded, or a snapshot
+                // message from the embedded editor is dropped as cross-origin.
+                return new URL(model.get("_runtime_url") || model.get("url") || "").origin;
+            } catch {
+                return null;
+            }
+        }
+        const onMessage = (event) => {
+            const data = event.data;
+            if (!data || data.type !== "metaframe-widget:shorturl" || !data.url) {
+                return;
+            }
+            // Route to the correct widget (one notebook may hold several) and
+            // verify the message came from our metaframe's origin.
+            const iframe = container.querySelector("iframe");
+            if (!iframe || event.source !== iframe.contentWindow) return;
+            const origin = expectedOrigin();
+            if (origin && event.origin !== origin) return;
+
+            model.set("saved_url", data.url);
+            model.save_changes();
+        };
+        window.addEventListener("message", onMessage);
+
+        // `_runtime_url` is derived from `url`, so this covers a url change too --
+        // and a change that maps to the SAME frame (the .app and .io spellings of
+        // one URL) correctly does not tear the iframe down.
+        model.on("change:_runtime_url", createMetapage);
+        model.on("change:saved_url", renderSavedUrl);
+
+        model.on("change:inputs", () => {
+            if (currentResult) {
+                const inputs = model.get("inputs");
+                currentResult.setInputs({ mf: inputs });
+            }
+        });
+
+        model.on("change:width", () => {
+            el.style.width = model.get("width") || "100%";
+        });
+
+        model.on("change:height", () => {
+            el.style.height = model.get("height") || "400px";
+        });
+
+        model.on("change:allow", applyAllowToIframes);
+
+        await createMetapage();
+
+        return () => {
+            window.removeEventListener("message", onMessage);
+            if (currentResult) {
+                currentResult.dispose();
+            }
+        };
+    },
+};
+"""

framejs-0.4.0/src/framejs/_widget.py

@@ -0,0 +1,151 @@
+import urllib.parse
+
+import anywidget
+import traitlets
+
+from ._esm import ESM
+
+#: Hosts serving the framejs *account* layer. Their /j/<id> URLs are the ones
+#: people copy and share, but they are not what a notebook should load.
+_APP_HOSTS = frozenset({"framejs.app", "www.framejs.app"})
+#: The host serving the frame *runtime*.
+_RUNTIME_HOST = "framejs.io"
+
+
+def runtime_url(url: str) -> str:
+    """Map a shareable ``framejs.app`` frame URL onto the ``framejs.io`` runtime.
+
+    ``framejs.app/j/<id>`` and ``framejs.io/j/<id>`` are the same frame, but only
+    framejs.io serves it as an embeddable metaframe with permissive CORS. The
+    framejs.app URL answers a framed request with a branded wrapper page, and its
+    ``/j/<id>/metaframe.json`` — which the metapage client fetches before it
+    renders anything — carries no ``Access-Control-Allow-Origin``. A notebook on
+    ``http://localhost:8888`` therefore gets::
+
+        Access to fetch at 'https://framejs.app/j/<id>/metaframe.json' from origin
+        'http://localhost:8888' has been blocked by CORS policy
+
+    and no widget. Normalising here means a user can paste either URL — the one
+    the share panel gives them is the framejs.app one — and it just works.
+
+    Anything that is not a framejs.app ``/j/`` URL is returned unchanged, so
+    full ``#?js=`` URLs, framejs.io URLs and local dev stacks are untouched.
+    Query and fragment are preserved (``?v=<sha256>`` pins a published version,
+    ``#?inputs=`` feeds the frame).
+    """
+    if not url:
+        return url
+    try:
+        parts = urllib.parse.urlsplit(url)
+    except ValueError:  # malformed; hand it back and let the browser complain
+        return url
+    host = (parts.hostname or "").lower()
+    if host not in _APP_HOSTS:
+        return url
+    if parts.path != "/j" and not parts.path.startswith("/j/"):
+        return url
+    return urllib.parse.urlunsplit(parts._replace(netloc=_RUNTIME_HOST))
+
+
+class Frame(anywidget.AnyWidget):
+    """Widget that renders a framejs frame in an iframe (Jupyter and marimo).
+
+    Args:
+        url: Full frame URL (including hash params).
+        inputs: Dict of inputs to push to the frame.
+        outputs: Dict of outputs received from the frame (read-only).
+        width: CSS width for the widget container (default "100%").
+        height: CSS height for the widget container (default "400px").
+        allow: iframe allow attribute string (e.g. "camera; microphone").
+        saved_url: Latest expiring snapshot URL (/j/<sha256>) minted by the
+            "Create expiring snapshot" button inside the widget (read-only).
+            Handy for a quick capture; for anything you want to keep, Save a
+            durable /j/<uuid> frame and use that URL instead.
+    """
+
+    _esm = ESM
+
+    url = traitlets.Unicode("").tag(sync=True)
+    inputs = traitlets.Dict({}).tag(sync=True)
+    outputs = traitlets.Dict({}).tag(sync=True)
+    width = traitlets.Unicode("100%").tag(sync=True)
+    height = traitlets.Unicode("400px").tag(sync=True)
+    allow = traitlets.Unicode("").tag(sync=True)
+    # The URL the iframe ACTUALLY loads: `url` mapped through runtime_url().
+    # Kept as its own synced trait rather than rewriting `url`, so reading back
+    # `w.url` returns exactly what the caller passed. The ESM uses this for both
+    # the iframe src and the postMessage origin check -- those two must agree or
+    # snapshot URLs from the embedded editor are silently discarded.
+    _runtime_url = traitlets.Unicode("").tag(sync=True)
+    # Set by the ESM when the user clicks "Create expiring snapshot" inside the
+    # embedded editor. Read-only from Python's perspective; updating it does not
+    # reload the iframe (so editing is not interrupted).
+    saved_url = traitlets.Unicode("").tag(sync=True)
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # Sync layout.height/width so ipywidgets' LayoutView doesn't clear
+        # the styles that the ESM sets on the element.
+        self.layout.height = self.height
+        self.layout.width = self.width
+        self.observe(self._sync_layout_height, names=["height"])
+        self.observe(self._sync_layout_width, names=["width"])
+        self._runtime_url = runtime_url(self.url)
+        self.observe(self._sync_runtime_url, names=["url"])
+
+    def _sync_runtime_url(self, change):
+        self._runtime_url = runtime_url(change["new"])
+
+    def _sync_layout_height(self, change):
+        self.layout.height = change["new"]
+
+    def _sync_layout_width(self, change):
+        self.layout.width = change["new"]
+
+    def set_inputs(self, d: dict):
+        """Merge a dict into the current inputs."""
+        self.inputs = {**self.inputs, **d}
+
+    def set_input(self, key: str, value):
+        """Set a single input key."""
+        self.inputs = {**self.inputs, key: value}
+
+    def on_outputs_change(self, callback):
+        """Register a callback for when outputs change.
+
+        The callback receives a change dict with 'old' and 'new' keys.
+        """
+        self.observe(callback, names=["outputs"])
+
+    def on_saved_url_change(self, callback):
+        """Register a callback for when the user creates an expiring snapshot.
+
+        Fires after the user clicks "Create expiring snapshot" inside the
+        embedded editor. The callback receives a change dict whose 'new' key
+        holds the freshly-minted /j/<sha256> snapshot URL.
+        """
+        self.observe(callback, names=["saved_url"])
+
+    def pipe_to(self, target: "Frame", output_key: str, input_key: str = None):
+        """Connect an output of this widget to an input of another.
+
+        When this widget's output_key changes, push the value to
+        target's input_key (defaults to output_key if not specified).
+        """
+        if input_key is None:
+            input_key = output_key
+
+        def _forward(change):
+            new_outputs = change.get("new", {})
+            if output_key in new_outputs:
+                target.set_input(input_key, new_outputs[output_key])
+
+        self.observe(_forward, names=["outputs"])
+
+
+#: Deprecated alias. The class was called ``MetaframeWidget`` while the package
+#: was published as ``metaframe-widget``; both were renamed in 0.4.0. Kept so
+#: notebooks and copied snippets written against the old name keep running --
+#: it is the same class, not a subclass, so ``isinstance`` and ``pipe_to``
+#: between the two names behave identically.
+MetaframeWidget = Frame

framejs-0.4.0/tests/test_widget.py

@@ -0,0 +1,211 @@
+from framejs import Frame
+
+
+def test_create_widget():
+    w = Frame(url="https://framejs.io/#?js=abc")
+    assert w.url == "https://framejs.io/#?js=abc"
+    assert w.inputs == {}
+    assert w.outputs == {}
+    assert w.height == "400px"
+
+
+def test_set_inputs():
+    w = Frame()
+    w.set_inputs({"a": 1, "b": 2})
+    assert w.inputs == {"a": 1, "b": 2}
+    w.set_inputs({"b": 3, "c": 4})
+    assert w.inputs == {"a": 1, "b": 3, "c": 4}
+
+
+def test_set_input():
+    w = Frame()
+    w.set_input("x", 42)
+    assert w.inputs == {"x": 42}
+    w.set_input("y", "hello")
+    assert w.inputs == {"x": 42, "y": "hello"}
+
+
+def test_on_outputs_change():
+    w = Frame()
+    changes = []
+    w.on_outputs_change(lambda change: changes.append(change))
+    w.outputs = {"key": "value"}
+    assert len(changes) == 1
+    assert changes[0]["new"] == {"key": "value"}
+
+
+def test_pipe_to():
+    source = Frame()
+    sink = Frame()
+    source.pipe_to(sink, output_key="doubled", input_key="data")
+    source.outputs = {"doubled": [2, 4, 6]}
+    assert sink.inputs == {"data": [2, 4, 6]}
+
+
+def test_pipe_to_default_key():
+    source = Frame()
+    sink = Frame()
+    source.pipe_to(sink, output_key="result")
+    source.outputs = {"result": 42}
+    assert sink.inputs == {"result": 42}
+
+
+def test_pipe_to_ignores_unrelated_keys():
+    source = Frame()
+    sink = Frame()
+    source.pipe_to(sink, output_key="x")
+    source.outputs = {"y": 99}
+    assert sink.inputs == {}
+
+
+def test_layout_height_synced_on_init():
+    """layout.height must match the height trait so ipywidgets doesn't clear it."""
+    w = Frame()
+    assert w.layout.height == "400px"
+    assert w.layout.width == "100%"
+
+
+def test_layout_height_synced_with_custom_value():
+    w = Frame(height="600px", width="80%")
+    assert w.layout.height == "600px"
+    assert w.layout.width == "80%"
+
+
+def test_layout_height_updates_on_change():
+    """Changing height trait after init must propagate to layout."""
+    w = Frame()
+    w.height = "500px"
+    assert w.layout.height == "500px"
+    w.width = "50%"
+    assert w.layout.width == "50%"
+
+
+def test_pipe_chain_five_widgets():
+    """Five widgets piped in a chain propagate data end-to-end."""
+    w1 = Frame()
+    w2 = Frame()
+    w3 = Frame()
+    w4 = Frame()
+    w5 = Frame()
+
+    w1.pipe_to(w2, output_key="data")
+    w2.pipe_to(w3, output_key="data")
+    w3.pipe_to(w4, output_key="data")
+    w4.pipe_to(w5, output_key="data")
+
+    # Simulate w1 producing output
+    w1.outputs = {"data": [1, 2, 3]}
+    assert w2.inputs == {"data": [1, 2, 3]}
+
+    # Simulate w2 producing output
+    w2.outputs = {"data": [2, 4, 6]}
+    assert w3.inputs == {"data": [2, 4, 6]}
+
+    # Simulate w3 producing output
+    w3.outputs = {"data": [6, 12, 18]}
+    assert w4.inputs == {"data": [6, 12, 18]}
+
+    # Simulate w4 producing output
+    w4.outputs = {"data": [16, 22, 28]}
+    assert w5.inputs == {"data": [16, 22, 28]}
+
+
+# --- the rename (0.4.0: metaframe-widget/MetaframeWidget -> framejs/Frame) ----
+
+
+def test_metaframe_widget_alias_is_the_same_class():
+    """`MetaframeWidget` is an ALIAS, not a subclass.
+
+    Old notebooks keep working, and a widget built under either name pipes to,
+    and isinstance-checks against, the other.
+    """
+    from framejs import MetaframeWidget
+
+    assert MetaframeWidget is Frame
+
+    source = MetaframeWidget()
+    sink = Frame()
+    assert isinstance(source, Frame)
+    source.pipe_to(sink, output_key="x")
+    source.outputs = {"x": 1}
+    assert sink.inputs == {"x": 1}
+
+
+def test_package_exports():
+    import framejs
+
+    assert sorted(framejs.__all__) == ["Frame", "MetaframeWidget", "runtime_url"]
+
+
+# --- framejs.app -> framejs.io normalisation ---------------------------------
+# A notebook must load the RUNTIME (framejs.io), not the account layer: only
+# framejs.io serves /j/<id>/metaframe.json with CORS headers, and the metapage
+# client fetches that before it renders anything. Pasting the framejs.app URL —
+# which is the one the share panel hands out — otherwise fails with a bare CORS
+# error and no widget.
+
+import pytest
+
+from framejs import runtime_url
+
+
+@pytest.mark.parametrize(
+    "given,expected",
+    [
+        # the case from the bug report
+        (
+            "https://framejs.app/j/019f61392e0778f8aba8dd7ffe35a83c",
+            "https://framejs.io/j/019f61392e0778f8aba8dd7ffe35a83c",
+        ),
+        # a pinned version and hash inputs must survive the swap
+        (
+            "https://framejs.app/j/abc?v=deadbeef#?inputs=eyJhIjoxfQ==",
+            "https://framejs.io/j/abc?v=deadbeef#?inputs=eyJhIjoxfQ==",
+        ),
+        ("https://www.framejs.app/j/abc", "https://framejs.io/j/abc"),
+        ("https://FrameJS.App/j/abc", "https://framejs.io/j/abc"),
+    ],
+)
+def test_app_frame_urls_are_mapped_to_the_runtime(given, expected):
+    assert runtime_url(given) == expected
+
+
+@pytest.mark.parametrize(
+    "url",
+    [
+        "",
+        # already the runtime
+        "https://framejs.io/j/abc",
+        # a full inline-code URL has no /j/ path
+        "https://framejs.io/#?js=YWxwaGE=",
+        # not a frame route: /f/ is the file endpoint
+        "https://framejs.app/f/abc",
+        "https://framejs.app/dashboard",
+        # must not be fooled by a lookalike host
+        "https://framejs.app.evil.com/j/abc",
+        "https://notframejs.app/j/abc",
+        # a local dev stack has no framejs.io counterpart we could name
+        "https://framejs-app.localhost:13829/j/abc",
+    ],
+)
+def test_other_urls_are_left_alone(url):
+    assert runtime_url(url) == url
+
+
+def test_widget_exposes_both_the_given_and_the_runtime_url():
+    app = "https://framejs.app/j/019f61392e0778f8aba8dd7ffe35a83c"
+    io = "https://framejs.io/j/019f61392e0778f8aba8dd7ffe35a83c"
+
+    w = Frame(url=app)
+    # What the caller passed is read back unchanged...
+    assert w.url == app
+    # ...while the iframe loads the runtime.
+    assert w._runtime_url == io
+    # The ESM needs it over the wire, or it falls back to the CORS-blocked URL.
+    assert "_runtime_url" in w.keys
+
+    # It tracks later assignments too.
+    w.url = "https://framejs.app/j/other"
+    assert w._runtime_url == "https://framejs.io/j/other"
+    w.url = "https://framejs.io/#?js=YWxwaGE="
+    assert w._runtime_url == w.url