Every open-source metaframe served from one
Fresh app on Cloudflare Workers, with each metaframe a
directory under ./frames/.
This replaces one-repo-and-one-deployment per metaframe: ~13 projects on Deno Deploy (which is shutting down) and ~26 GitHub Pages sites, each carrying its own copy of the same build config and the same ~300 lines of UI chrome.
just dev # https://localhost:5173Every frame answers on two URL forms:
| form | example | why |
|---|---|---|
| subdomain | https://markdown.mtfm.io/#?md=… |
what published metapages already embed — these URLs keep working |
| path | https://mtfm.io/markdown/#?md=… |
one origin, and what dev uses |
Subdomain requests are rewritten to the path form before Fresh routes them, so
there is exactly one route per frame. See lib/host.ts and the
App.handler() override in main.ts.
Each frame also serves:
/<frame>/metaframe.json— the definition the embedding metapage reads/<frame>/README.md— the in-app help, rendered by the markdown frame
Both are CORS-open, because metaframes are always embedded cross-origin.
just new <name> # scaffolds frames/<name>/ from ./templatesA frame is four files:
frames/<name>/frame.ts metadata: title, hosts[], metaframe.json, headers
frames/<name>/options.ts declarative Options tab schema
frames/<name>/index.tsx the route; computes the help URL server-side
frames/<name>/(_islands)/Main.tsx the UI
frames/<name>/README.md in-app help
static/<name>/... images and other per-frame assets
Nothing central needs editing: lib/registry.ts picks up
frames/*/frame.ts with an eager glob.
Inside frames/<name>/, only index.* is a route — co-located modules are
excluded by the ignore rule in vite.config.ts. Islands go
in (_islands)/.
The point of the monorepo. Most of a metaframe used to be these:
components/FrameShell.tsx |
Main / Options / Help tabs, the editor chrome modes, copy-URL button. Tabs mount on first use and stay mounted. |
components/PanelColumn.tsx |
the panel beside the renderer and the handle that resizes the split, remembered per viewer in localStorage |
components/OptionsPanel.tsx |
the settings panel, generated from a frame's FrameOption[]. Fields share one options hash param; a field marked hashParam gets its own top-level param instead, for values that are part of what the frame is (molstar's pdbId) rather than how it looks. A standalone param equal to its declared default is written as absent |
components/shellOptions.ts |
settings the shell adds to every frame's panel, currently the editor control |
lib/hash/useHashParam.ts |
Preact hooks over @metapages/hash-query, wire-compatible with every published URL |
lib/metaframe/useMetaframe.ts |
the metaframe postMessage protocol as hooks: inputs, outputs |
components/CodeMirror.tsx |
editor, grammars loaded on demand |
A frame's renderer sits in one fixed position in a single element tree and is never moved or unmounted by the chrome. Everything else — an editor, settings, help — is the menu, and opens in one shared column beside it. Hiding the menu hides all of it, so an embedded frame is just the renderer.
Two rules fall out of that, and both exist because breaking them caused real bugs:
-
Never branch the element tree on chrome state. Returning a different tree for "menu hidden" makes Preact recreate the renderer's DOM node. Any frame that writes its own HTML (markdown, and later mermaid, plotly, molstar, jsoncrack) then goes silently blank, because the effect that filled the node does not re-run.
FrameShellrenders one tree and toggles pieces inside it. -
A frame that injects HTML must hold its node in state, not a ref. Use a ref callback (
ref={setRoot}) and put the node in the effect's deps, so the content is rewritten if the node is ever replaced:const [root, setRoot] = useState<HTMLDivElement | null>(null); useEffect(() => { if (!root) return; root.innerHTML = render(...); }, [root, ...]); return <div ref={setRoot} />;
The header holds one selection, and always one. Panels behave like tabs — opening one closes the last — because two lit buttons read as two independent toggles. The buttons are a selection rather than toggles: clicking the open panel's own button does nothing, and no panel has a close button. Every frame has at least settings and help, so there is always something to be looking at, and the menu's close button already says the thing "no panel" would. Plain actions (copy, links) never render as selected. State travels between a panel and the renderer through hash params only, so neither needs to know about the other.
edit=true opens the whole authoring surface: the header bar, and a panel
beside the renderer. Without it a frame is only its renderer — no header,
no panels, none of the editor fetched. That is what an embed is, and what a
shared link should be, which is why the copy action strips edit from the URL
it puts on the clipboard while leaving the page you are working in alone.
Opening the menu lands on the frame's first declared panel (the editor, for
markdown), or on the first panel the shell provides for a frame that declares
none — so edit=true always shows something. Closing the menu is the only way
back to the bare renderer: the panel column itself never empties.
editor decides how reachable the menu is, which is the same question as
whether this frame's content can be edited at all. It is what an embedding
system sets to answer that, and it keeps the vocabulary of hm, the name it
was published under:
| value | behaviour |
|---|---|
absent / invisible |
the open-menu button is transparent until hovered, but always clickable |
visible |
the open-menu button is always drawn |
disabled |
no menu and no button, ever — the content is read-only here |
It is settable from the settings panel of every frame, which is where the
published editor put it ("Button Visibility"). The shell contributes that row
to each frame's form — see
components/shellOptions.ts — so no frame
declares it, and a frame with no settings of its own still has a settings
panel. Choosing Hidden switches the control off with it, exactly as v1
warned in its own label: nothing can reopen the menu without removing
editor=disabled from the URL.
hm is still read, and forever: every metaframe deployed so far writes it,
and the help convention all of them embed is
https://markdown.mtfm.io/#?hm=disabled&url=…/README.md, which lands here the
moment this deployment takes over that host. editor wins when both are
present, and editor is the only one written. true/false are accepted as
synonyms for visible/disabled, because that is what a caller means by "is
this editable". See lib/hash/useEditorMode.ts.
The panel column is resizable: drag the handle on its left edge, or focus it
and use the arrow keys (shift for a coarser step, Home to reset — double-click
does the same). The width is stored in localStorage under
mtfm:panel-width:<frame>: one split per frame, shared by the editor, the
settings and the help panel. Keying it per panel instead meant dragging the
settings wider, reopening the editor, and finding the same split back at its
default.
It is deliberately not a hash param. How wide someone likes their editor is
not part of the document, and must not travel in a shared URL. A frame may
still declare a starting width (markdown's editorWidth, default 80ch); the
first drag replaces it for that viewer, and both are clamped so neither side of
the split can be squeezed below 160px.
The URL hash is a frame's state, and @metapages/hash-query
owns its wire format. Never hand-roll any part of it — no atob/btoa, no
location.hash slicing, no string-concatenated #?a=1&b=2. Use the Preact
wrappers in lib/hash/useHashParam.ts, or the
module's own getters, setters and addEventListenerHashParam* subscriptions
outside a component. Full rules, including the compatibility constraints that
keep published metapage URLs working, are in the hash-params skill
(.claude/skills/hash-params/SKILL.md).
A frame with an editor should not hand-roll the editing loop either. Use
lib/hash/useHashParamDocument.ts, which
renders from local state immediately, debounces the hash write, and ignores
that write coming back — getting any of those wrong is invisible until someone
says typing feels broken. components/CodeMirror.tsx guards the other
direction, refusing to let the echo of its own edit overwrite the buffer.
The page is small and renders content; anything heavier is fetched when it is actually needed. Measured on the production build:
| frame | first load | on demand |
|---|---|---|
/echo |
208 KB | — |
/molstar |
211 KB | ~5 MB Mol* when a structure arrives |
/pyodide |
214 KB | the Python runtime when it starts |
/markdown |
347 KB | ~610 KB editor when the menu opens |
About 210 KB of that is the floor every frame pays: the client entry, the
shared shell, and @metapages/metapage.
The rule for a new frame: import a heavy dependency dynamically, inside the
component that needs it. Vite then splits it into its own chunk and the
browser fetches it on mount, not on load.
components/CodeMirror.tsx is the worked
example — every CodeMirror import is dynamic and only the types are imported
statically, so a markdown frame opened read-only ships none of the editor.
Some libraries cannot be bundled at all. Mol*'s module entry
(molstar/lib/apps/viewer/app.js) imports node:crypto, node:fs and
node:path, so it fails at load in a browser; build/viewer/molstar.js is a
self-contained browser build instead, which is what Mol*'s own embedded.html
uses. Pyodide only ships a classic script. For those, load the browser build at
runtime with lib/cdn.ts — which keeps them out of the first
load for free.
What legitimately belongs in the initial chunk is the frame's actual content
renderer (markdown-it for the markdown frame) and @metapages/metapage, which
has to connect to the parent metapage promptly to receive inputs.
just # list commands and URLs
just dev # dev server, all frames, both URL forms
just check # fmt, lint, type-check, unit tests
just build # production build into ./_fresh
just start # serve the build on Deno
just preview # serve the build on workerd (the real runtime)
just preview-host markdown.mtfm.io # ...as a frame subdomain
just deploy # check, build, wrangler deploy
just logs # tail production logsjust dev serves over HTTPS once mkcert has run (it runs automatically). That
is not cosmetic: an https parent page cannot embed an http iframe, so testing a
frame the way it is actually used needs TLS locally.
wrangler.jsoncpointsmainat_fresh/server.js, which Fresh emits already shaped as{ fetch }.- The Cloudflare Vite plugin is deliberately not used: it builds the worker
environment in the same pass that produces
_fresh/server.js, which the worker entry imports, so the build races itself.vite buildthenwrangler deployhas no such problem. - Static files are served by Cloudflare's assets layer from
_fresh/client, not by the Worker — Fresh's production build cache reads them withDeno.open, which does not exist on workerd. - Because the assets layer answers before the Worker runs, it cannot see the
subdomain rewrite. Per-frame assets must therefore be referenced as
/<frame>/…; a frame's README has its relative image paths rewritten to that form when served (seelib/markdown/links.ts). - Production subdomains need a proxied wildcard DNS record for
*.mtfm.io; Universal SSL covers one level of wildcard. wrangler devpins the simulated hostname to the firstroutesentry, so usejust preview-host <host>to exercise subdomain routing locally.
| frame | from | notes |
|---|---|---|
echo |
metaframe-echo |
✅ |
markdown |
metaframe-markdown, metaframe-markdown-v2 |
✅ serves markdown + the legacy markdownv2 alias; renders every frame's help |
pyodide |
metaframe-pyodide, metaframe-py-NEW |
✅ serves py + the legacy pyiodide alias; Python runtime from a CDN |
molstar |
metaframe-molstar |
✅ Mol* browser build from a CDN; PDB id, .pdb, .cif, gromacs trajectory |
The rest are still deployed from their own repos. The UI of each is rewritten to
Preact + Tailwind on migration — the originals are React 18 + Chakra UI v2, and
preact/compat plus emotion plus framer-motion is not a combination worth
carrying forward.