Browser preview

This page is for developers working on the Oda codebase. DataMind Oda's browser preview runs the whole application inside one dedicated Web Worker on a browser page, with nothing installed. It backs preview deployments and the packaging checks that exercise a build in a browser.

Three parts ship together: the runtime library that assembles the worker, the worker bundle that runs the application, and the page connector that links the page to the worker. The build packs the application into a single image file, and the worker mounts that image when it starts.

Start a preview

1. Open the preview page. When its address carries no fixture, the source chooser renders before the worker starts. Its heading is Choose Preview data, the choice is labelled Filesystem source, and the copy explains the timing: Data mounts before the Worker and application start. Refresh to choose again.
2. Choose a source and press Start Preview. The page connector fetches the base image and the source's overlays, then the worker mounts them and boots the application.

You can also skip the chooser altogether: ?preview-fixture=<id> starts from that fixture, and the value none starts with no overlays. A value that names no known fixture is refused without showing the chooser.

The chooser follows the page's light or dark theme and respects the system's reduced-motion preference.

What the preview can start from

• Empty environment starts from the image alone, described as Load only the base runtime to verify first launch and workspace creation.
• WebFS directory is disabled: it needs directory access that the preview does not provide.
• The chooser also lists the fixtures the manifest defines. When you make no choice, it preselects the manifest's default fixture; when the manifest names no default, it starts with no fixture overlays.
• For authoring fixtures and the sample data they carry, see Preview fixtures and sample data.

What the preview mounts

• The worker mounts an in-memory filesystem of its own: a home folder for durable state, a workspace, a temp area, a mount of the application's modules, and the composed configuration.
• The image is a single gzip member wrapping an uncompressed archive: regular files and directories only. A name the archive format cannot store stops the packing step instead of producing a broken image.
• The source's overlays replace files only under the home and workspace folders; they cannot replace the configuration or the module code.
• Commands run in a preview go through its own shell: The preview shell covers the command set. What the filesystem and the runtime do not support is on Preview limitations.

How it boots and serves

1. The page connector fetches the base image and the source's ordered overlays, and hands the worker its start message.
2. The worker checks the message, inflates the image, mounts its files into the in-memory filesystem, and applies the source's overlays.
3. It checks that the image was prepared for this exact build. The worker holds no compiler, so an image from another build is refused and must be rebuilt.
4. It boots the application. Requests that arrive before it is serving queue, and dispatch once it is.

• No socket is opened: the application's server reports a successful bind, but every request travels over the page connector to the worker. Requests are presented under a loopback host that the page cannot set.
• One request, the boot payload, is answered by the worker itself before the application exists, GET only and never cached.
• API methods that need the worker's own direct access are answered on a direct path rather than through the route table; a 401 or 403 the route table returns for one of those calls is retried once on the direct path. Everything else runs through the application's real request routes, so its checks, size limits and status codes stay in force.
• The worker forwards warnings and errors to the browser console; routine progress logging is dropped.

Questions, answered

Do I need to install anything to run a preview?

No. The preview is a browser page: the worker runs the application from its image, and nothing is installed.

How do I open a preview with a specific fixture?

Name it in the address: ?preview-fixture=<id> skips the chooser and supplies that fixture's overlays, and ?preview-fixture=none opens with no overlays. For authoring fixtures, see Preview fixtures and sample data.

What does the preview start from when I make no choice?

The manifest's default fixture; when the manifest names no default, it starts with no fixture overlays, as Empty environment does.

Why is WebFS directory disabled?

It needs directory access that the preview does not provide. Use a fixture or Empty environment instead.

Where do the preview's files live?

In the worker's in-memory filesystem: a home folder for durable state, a workspace, a temp area, the application's modules and the composed configuration. What that filesystem does and does not support is on Preview limitations.

What happens when I refresh the page?

The worker starts again: the chooser returns before it starts, and anything that lived only in the previous run, edits included, does not come back. The chooser says so: Refresh to choose again.

How does the preview serve requests if nothing is listening on a port?

Nothing is listening, because the preview opens no socket. The application's server reports a successful bind, but requests travel over the page connector to the worker, where the application's real routes handle them.

Why was my image refused after a rebuild?

The image records the build that prepared it, and the worker holds no compiler: it runs only an image prepared by its own build. Repack the image; the refusal tells you to rebuild it.

What does the preview show in the browser console?

Warnings and errors from the running application; routine progress logging is dropped. What each message means is on Preview diagnostics.

Can I run the preview in dark mode?

Yes. The chooser follows the page's light or dark theme, and it respects the system's reduced-motion preference.