browser-substrate

The command that brings a project into a browser tab. Run it in the project's folder on your machine:

npx @volter/browser-substrate dev

It reads the folder's setup (a Dockerfile or compose file, or else package.json with its lockfile, pyproject.toml or requirements.txt, a Procfile), prepares the image on your machine, and opens a tab that runs it. Everything before the project's CMD happens here, once: dependencies are resolved by the package manager the lockfile names and prepared as packs. The tab links those packs and runs CMD; it does not install, clone or build (see the repository README's four rules).

To change what the tab has, change the folder and run dev again: a new dependency goes in the lockfile, a new program in the Dockerfile. Something added to a running tab without a new image comes from the catalog as a live pack.

Commands

| Command | What it does | |---|---| | browser-substrate dev | Prepare this folder's image and run it in a tab, attached to a World. -- <command> names what serves it, in place of what the folder's files say. | | browser-substrate build | Write ./dist: the page and the image, deployable to any static host. | | browser-substrate preview | Serve ./dist locally with its isolation headers. | | browser-substrate init | Write a playground Dockerfile and bootstrap.mjs into an empty folder. | | browser-substrate dockerfile | Write a Dockerfile from what this folder carries. |

browser-substrate with no command prints every option.

For a prepared Next production app, entries/start-next-on-demand.cjs is an optional image entry. It selects Next's preloadEntriesOnStart: false, keeping unrelated routes out of startup; their first request loads them normally. Pass its source to node -e so Next resolves from the application's directory:

NEXT_IMAGE_ENTRY=$(node -p "require.resolve('@volter/browser-substrate/entries/start-next-on-demand.cjs')")
browser-substrate dev --world /path/to/world --dir apps/web --build '<project build command>' \
  -- node -e "$(cat "$NEXT_IMAGE_ENTRY")"

The entry reads the build's normalized .next/required-server-files.json config (set NEXT_IMAGE_DIST_DIR for a custom build directory) and uses Next's own standalone configuration seam and CLI. It refuses versions without that scheduling option. It does not edit the project or its installed framework.

In a tab

A tab also registers a browser-substrate program. Typed there, dev reads the setup of a folder already in the tab and starts its dev command. A folder that arrived without a prepared image has nothing to link, and its install is refused, never run: the tab installs nothing (Article 1).

Words used here are defined in the glossary.

Shared Workbench programs

@volter/browser-substrate/programs.js exports createWorkbenchPrograms(options, host). The returned definitions have id, title, icon and mount(element, { close }); mounted views support show, hide, refresh and dispose. The program set owns sessions and releases them on dispose. A window host mounts on first open and hides without disposing when a window closes.

mountToolbar consumes these same definitions. Its buttons are icon shortcuts to floating windows. No tool or shell starts unless opened explicitly (including terminal: { open: true }); stored visibility is ignored. A desktop consumes the definitions directly and supplies its own window manager.

share.sources returns named ShareSource objects with id, title, kind, optional supported audience modes, and open(access, signal). The result is a ShareHandle; the host remains responsible for authorization and publication. The existing port-sharing callback remains supported. screen-share-source.js supplies the AlmostCDP adapter for a substrate preview; the prepared viewer is view only and shows DOM reconstruction, not canvas/video. See ADR-0058.