create-gesso-app 0.1.0

package/templates/electrobun/README.md

@@ -0,0 +1,209 @@
+# {{name}}
+
+A Gesso application in a native window. The interface is built, laid
+out, painted and hit-tested in a render worker; the window's own main
+thread carries frames between that worker and the main process and does
+nothing else. The state lives in the main process, so every window is a
+replica of one source and two windows agree without anything
+synchronising them.
+
+```
+main process (Cottontail)               window 1              window 2
+  count: BehaviorSubject             shell + worker        shell + worker
+  Counter channel          ------>   replica -> screen     replica -> screen
+  DesktopWindows channel   <------   commands              commands
+```
+
+## Getting the toolchain
+
+Electrobun 2.x is delivered by a launcher called **Hutch**, not by a
+package manager. `hutch electrobun prepare` projects the SDK into
+`.hutch/devkit` inside this project, which is why there is no
+`electrobun` entry in `package.json` and why adding one would not help:
+the npm package of that name is only a bootstrap that downloads the
+toolchain.
+
+If `hutch` is not on your path yet, the bootstrap is what fetches it.
+Any command will do; this one only prints Hutch's help:
+
+```sh
+npx electrobun@2.0.1 --help
+```
+
+That leaves the launcher at
+`~/.hutch/npm/electrobun/2.0.1/<platform>/bin/hutch` (for example
+`linux-x64` or `darwin-arm64`). Put that directory on your path, or call
+the binary by its full path. `HUTCH_HOME` can point somewhere disposable
+to keep the downloaded toolchain out of `~/.hutch`; the launcher then
+lands under that directory instead.
+
+## Running it
+
+```sh
+hutch install       # dependencies, including the vendored Gesso packages
+hutch run dev       # prepare, build the window's assets, open the window
+```
+
+`hutch install` runs npm underneath, because `hutch.config.ts` says
+`packageManager: 'npm'`: Hutch's own resolver reads a relative `file:`
+override against the package that asked for it rather than against this
+directory, and stops with `FileNotFound` on the second vendored package.
+npm reads `overrides` from here, which is what the tarballs in `vendor/`
+need. You will see a `package-lock.json`, and no `hutch.lock`.
+
+`hutch run build` makes a distributable build under `build/stable-*`,
+and `hutch run typecheck` checks the types without building. Every
+script runs `hutch electrobun prepare` first, because both
+`vite.config.ts` and `tsconfig.json` read the SDK out of `.hutch/devkit`
+and neither can be loaded before it exists.
+
+The first line of `hutch.config.ts` pins the Hutch that runs these
+scripts to 0.24.3, the one the bootstrap above installs. The comment
+under it says why: the newer launcher fails the distributable build.
+Leave the line first in the file.
+
+In a development build, what the window logs to its console is printed
+by the main process, prefixed `[webview:1]`, so `console.log` in a
+component or in `src/view/main.ts` lands in the terminal you ran
+`hutch run dev` from.
+
+### Linux, on a Wayland desktop
+
+Electrobun opens its window as an X11 client, so under a Wayland
+compositor it runs through XWayland. On the machine this template was
+checked on (Hyprland, an NVIDIA GPU, WebKitGTK 2.52) the window came up
+as a blank surface: the log said `Failed to create GBM buffer` twice,
+the page had loaded, and nothing was ever composited. Putting
+
+```sh
+WEBKIT_DISABLE_DMABUF_RENDERER=1 hutch run dev
+```
+
+in the environment made it paint. It has to be in the environment of
+the launch; setting it from `src/main/index.ts` is too late, because
+the webview reads it as it starts. Nothing about this is Gesso's, and a
+desktop where the log has no GBM line does not need it.
+
+## What has been checked
+
+On 2026-09-16, on Linux x64 with WebKitGTK 2.52.6 and Electrobun 2.0.1,
+a project written by this template was installed by `hutch install`,
+typechecked by `hutch run typecheck`, built by `hutch run build` to
+`build/stable-linux-x64`, and opened by `hutch run start` with the
+variable above set. The window painted in the dark appearance with the
+counter at `0`. A press on **Count** reached the main process, which
+logged the increment, and the window painted `1`. A press on **Dark**
+turned the window light. A press on **New window** opened a second
+window already reading `1`, `2 windows, one source`, and light. The
+presses were dispatched to the canvas from inside the page, because
+that desktop had no way to inject a pointer into an X11 window; the
+path from the canvas inward is the one a real pointer takes, and the
+path from a real pointer to the canvas is the platform's.
+
+Nothing has been run on macOS or Windows, so on WKWebView and WebView2
+this project is a build and a first window away from being known to
+work. `hutch run dev` was not used for the check, only `hutch run
+start`, which is the same command without `--watch`.
+
+Press **Count** and the number changes. Press **New window** and a
+second window opens already showing the current value, because it
+replicates the same source rather than being handed a copy. Flip
+**Dark** and every open window changes appearance, because the
+appearance is the main process's setting and not the window's, and
+because `App.tsx` binds its theme to what the shell reports.
+
+## What is where
+
+| Path                        | What it is                                                              |
+| --------------------------- | ----------------------------------------------------------------------- |
+| `src/shared/Counter.ts`     | The channel both processes import. The whole of what they share.        |
+| `src/shared/rpc.ts`         | The one message a window and the main process exchange.                 |
+| `src/main/index.ts`         | The main process: the state, the windows, and what a link outside does. |
+| `src/view/main.ts`          | A window's main thread: build the bridge, mount, and nothing else.      |
+| `src/view/render.worker.ts` | The render worker: the root component and the channels it attaches.     |
+| `src/render/App.tsx`        | The screen.                                                             |
+
+Three lines carry weight:
+
+```ts
+renderWorker: () => new Worker(new URL('./render.worker.ts', import.meta.url), { type: 'module' });
+```
+
+That expression has to stay written out. A bundler emits a chunk for a
+worker it can see constructed, and it cannot see through a variable
+holding the URL. `electrobun.config.ts` copies the chunk it emits into
+the bundle, which is how the worker loads from a `views://` url.
+
+```json
+"jsx": "react-jsx",
+"jsxImportSource": "gesso-framework"
+```
+
+Those two lines in `tsconfig.json` are the whole of what makes `<row>`
+and `<text>` work, and `vite.config.ts` repeats them for esbuild. JSX
+here is a spelling rather than a runtime: it compiles onto the element
+factories and produces the identical tree.
+
+## The one rule about the window's main thread
+
+A patch goes from the main process into the render worker as a body the
+window's main thread carries and never reads. It multiplexes streams
+and knows nothing about channels, components or patches. Keep it that
+way: the moment that thread has to understand a payload in order to
+route it, work that belongs in a worker has moved onto the thread that
+draws, and a frame can be late because of it.
+
+## Why the main process is not pre-bundled
+
+`electrobun.config.ts` points Cottontail at `src/main/index.ts` and lets
+Electrobun bundle it, which is the ordinary arrangement. Gesso's own
+Electrobun applications do not do this: they pre-bundle their main
+process with esbuild first, because they import the framework out of a
+workspace rather than out of `node_modules`, and a bundler cannot
+resolve a package that was never installed. Here the packages are
+installed, in `vendor/`, so the ordinary arrangement is the right one.
+
+If a future toolchain ever fails to resolve `gesso-electrobun` from the
+main process, that is the escape hatch: bundle `src/main/index.ts` to a
+plain `.js` file with `electrobun/main` left external, and point the
+`cottontail.entrypoint` at the bundle instead.
+
+## Why `vendor/` exists, and how to remove it
+
+Gesso is not published to a registry yet. A `package.json` naming a
+version of `gesso-core` would produce a project that cannot install, so
+`create-gesso-app` packed the packages out of its own workspace, put the
+tarballs in `vendor/` and pointed `dependencies` and `overrides` at
+them:
+
+```json
+"gesso-core": "file:vendor/gesso-core-0.1.0.tgz"
+```
+
+`overrides` is there because the packages declare each other by version
+range, and without it an installer is free to go looking for
+`gesso-core@^0.1.0` on a registry that has never heard of it.
+
+To pick up a change made in the Gesso workspace, run `create-gesso-app`
+again over this directory with `--force`, or repack by hand:
+
+```sh
+cd path/to/gesso && pnpm --filter './packages/*' build
+cd packages/core && pnpm pack --pack-destination path/to/this/project/vendor
+```
+
+When the packages are published this all goes away: delete `vendor/`,
+delete `overrides`, and put version ranges back in `dependencies`.
+
+## Where to go next
+
+- `src/render/App.tsx` is commented with what each part of it is doing.
+- A channel is the barrier: view keys out, typed commands in, plain
+  data only. Add a key to `CounterView`, serve it in `src/main`, read it
+  in a component, and nothing in between has to change.
+- A command crossing to the main process costs about a frame and a
+  half, because every message is serialised, encrypted and sent over a
+  socket. Patches are one way and pipelined, so they do not pay it;
+  anything that waits for an answer does.
+- `gesso-components` has the controls: inputs, overlays, structure,
+  data and media. `Switch` in `App.tsx` is one of them.

package/templates/electrobun/_gitignore

@@ -0,0 +1,10 @@
+node_modules
+dist
+build
+.cottontail-tmp
+*.local
+.DS_Store
+
+# Written by `hutch electrobun prepare`, and rewritten whenever the
+# Electrobun version in hutch.config.ts changes.
+.hutch

package/templates/electrobun/electrobun.config.ts

@@ -0,0 +1,49 @@
+import type { ElectrobunConfig } from 'electrobun';
+
+/**
+ * What Electrobun builds, and where it looks for it.
+ *
+ * `electrobun` resolves through `.hutch/devkit`, which
+ * `hutch electrobun prepare` writes. There is no `electrobun` package
+ * in `node_modules` and there is not meant to be: the SDK is projected
+ * into the project by the toolchain rather than installed from a
+ * registry.
+ */
+export default {
+  app: {
+    name: '{{name}}',
+    // Reverse DNS, and yours rather than this one. The operating
+    // system uses it to tell one application from another, so two
+    // applications sharing an identifier share a great deal else.
+    identifier: 'com.example.{{name}}',
+    version: '0.0.1'
+  },
+  build: {
+    mainProcess: 'cottontail',
+    cottontail: {
+      // A TypeScript entrypoint, which Electrobun bundles for itself.
+      // It reaches `gesso-electrobun` through `node_modules` like any
+      // other dependency, which is why this project vendors the
+      // packages rather than linking them: the Gesso repository's own
+      // Electrobun applications have to pre-bundle their main process
+      // with esbuild, because a workspace package is not installed
+      // anywhere the bundler can see it.
+      entrypoint: 'src/main/index.ts'
+    },
+    copy: {
+      // What Vite wrote, put where a `views://` url will look for it.
+      // The render worker is one of the chunks under `assets`, so the
+      // second line is what lets a window start a worker at all.
+      'dist/index.html': 'views/mainview/index.html',
+      'dist/assets': 'views/mainview/assets'
+    },
+    watchIgnore: ['dist/**'],
+    // Gesso paints through a 2D canvas, so the webview each platform
+    // already ships is enough. Bundling CEF would put Chromium, and
+    // therefore WebGPU, in the application on every platform, at a
+    // considerable size.
+    mac: { bundleCEF: false },
+    linux: { bundleCEF: false },
+    win: { bundleCEF: false }
+  }
+} satisfies ElectrobunConfig;

package/templates/electrobun/hutch.config.ts

@@ -0,0 +1,48 @@
+// @hutch cli=0.24.3
+/**
+ * What `hutch run <script>` does, and which Electrobun to fetch.
+ *
+ * Every script begins with `hutch electrobun prepare`, because that is
+ * the step that writes `.hutch/devkit`, and both `vite.config.ts` and
+ * `tsconfig.json` read the SDK from there. Electrobun is a toolchain
+ * Hutch downloads rather than a package a registry serves, so a
+ * project that skipped this would have nothing to build against.
+ *
+ * The first line of this file is a pragma Hutch reads, not a comment
+ * for you, and it has to stay the first line. It pins the Hutch that
+ * runs these scripts to the one the Electrobun 2.0.1 bootstrap installs
+ * and the one this template was checked with. Without it `hutch run`
+ * fetches the newest launcher, and on 2026-09-15 and again on
+ * 2026-09-16 that launcher (0.26.0) failed this project's distributable
+ * build: it expected a `cottontail-core` binary in the Cottontail
+ * release Electrobun 2.0.1 bundles into an application (0.5.0), which
+ * does not ship one, and stopped with `CopySourceMissing`. The dev
+ * build was unaffected. Move the pin and `electrobun.version` together,
+ * and check `hutch run build` when you do.
+ */
+export default {
+  // npm installs this project, not Hutch's own resolver. The vendored
+  // Gesso packages ask each other for version ranges no registry can
+  // answer, and `overrides` in package.json is what points those
+  // requests at the tarballs in vendor/. Hutch's built-in resolver
+  // resolves a relative `file:` override against the package that asked
+  // rather than against this directory, and fails with `FileNotFound`;
+  // npm resolves it from here. When the packages are published and
+  // vendor/ goes, this line can go with it.
+  packageManager: 'npm',
+  scripts: {
+    install: ['hutch', 'install'],
+    start: 'hutch electrobun prepare && hutch pm exec -- vite build && hutch electrobun dev',
+    dev: 'hutch electrobun prepare && hutch pm exec -- vite build && hutch electrobun dev --watch',
+    // The window's assets on Vite's dev server, and the application
+    // around them, so a change to a component reloads the webview
+    // without rebuilding the native side.
+    'dev:hmr': ['hutch', 'pm', 'exec', '--', 'concurrently', 'hutch run hmr', 'hutch run start'],
+    hmr: 'hutch electrobun prepare && hutch pm exec -- vite --port 5173',
+    build: 'hutch electrobun prepare && hutch pm exec -- vite build && hutch electrobun build --env=stable',
+    typecheck: 'hutch electrobun prepare && hutch pm exec -- tsc --noEmit'
+  },
+  electrobun: {
+    version: '2.0.1'
+  }
+};

package/templates/electrobun/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "gesso-electrobun-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "A Gesso application in a native Electrobun window.",
+  "dependencies": {
+    "gesso-components": "^0.1.0",
+    "gesso-core": "^0.1.0",
+    "gesso-electrobun": "^0.1.0",
+    "gesso-framework": "^0.1.0",
+    "rxjs": "^7.8.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "concurrently": "^9.1.0",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.3"
+  }
+}

package/templates/electrobun/src/main/index.ts

@@ -0,0 +1,90 @@
+/**
+ * The main process: the application's state, and the windows that
+ * replicate it.
+ *
+ * Nothing about a component, a layout or a pixel appears in this file,
+ * and nothing about a window appears in the render worker. What the
+ * two sides share is the channel token in `src/shared/Counter.ts`.
+ *
+ * A second window is free: `createDesktopApp` serves the same
+ * observables to every window it opens, each with its own record of
+ * what that window has already seen, so two windows agree by
+ * construction rather than by synchronising.
+ */
+import { BrowserView, BrowserWindow, Utils } from 'electrobun/main';
+import { BehaviorSubject, map } from 'rxjs';
+
+import type { GessoFrame } from 'gesso-electrobun';
+import { createDesktopApp, windowsChannel } from 'gesso-electrobun/desktop';
+
+import { Counter } from '../shared/Counter';
+import type { GessoWindowRPC } from '../shared/rpc';
+
+/** The application's whole state, in the process that owns it. */
+const count = new BehaviorSubject(0);
+
+/**
+ * The appearance every window is told about.
+ *
+ * The application owns it because Electrobun has no appearance API,
+ * and because the webview's own `prefers-color-scheme` is wrong on
+ * WebKitGTK. On a platform that has a signal this is where it would be
+ * fed from; here it is a setting, which is a perfectly good source.
+ */
+const dark = new BehaviorSubject(true);
+
+const app = createDesktopApp({
+  channels: window => [
+    {
+      token: Counter,
+      source: {
+        view: { count, dark },
+        commands: {
+          increment: (by: number) => count.next(count.value + by),
+          setDark: (next: boolean) => dark.next(next)
+        }
+      }
+    },
+    // What a window opens another window through. Without it a screen
+    // would have to import this adapter to do it.
+    windowsChannel(app, window)
+  ],
+  open: (receive, handle) => {
+    const rpc = BrowserView.defineRPC<GessoWindowRPC>({
+      maxRequestTime: 30_000,
+      handlers: {
+        requests: {},
+        // Wired before the window exists, because the first handshake
+        // arrives as soon as the page loads and a lost handshake is a
+        // window that never replicates anything.
+        messages: { gessoFrame: (frame: GessoFrame) => receive(frame) }
+      }
+    });
+    const window = new BrowserWindow({
+      title: '{{name}}',
+      url: 'views://mainview/index.html',
+      frame: { width: 460, height: 360, x: 100 + handle.id * 60, y: 120 + handle.id * 40 },
+      rpc
+    });
+    return {
+      send: (frame: GessoFrame) => window.webview.rpc?.send.gessoFrame(frame),
+      close: () => window.close()
+    };
+  },
+  colorScheme: dark.pipe(map(on => (on ? 'dark' : 'light'))),
+  onOpenUrl: url => {
+    // The application decides what it is willing to hand to the
+    // operating system; the adapter only carries the request.
+    if (url.startsWith('https://')) {
+      Utils.openExternal(url);
+    }
+  },
+  onLastWindowClosed: () => {
+    // A desktop application usually stops here. One with a tray or a
+    // menu bar would not, which is why this is a callback and not an
+    // exit the adapter takes on its own.
+    process.exit(0);
+  }
+});
+
+app.openWindow();

package/templates/electrobun/src/render/App.tsx

@@ -0,0 +1,100 @@
+import { map } from 'rxjs/operators';
+
+import { Switch } from 'gesso-components';
+import { darkTheme, lightTheme, percent } from 'gesso-core';
+import { DesktopWindows } from 'gesso-electrobun/desktop';
+import { ShellService, type ComponentContext, type Inputs } from 'gesso-framework';
+
+import { Counter } from '../shared/Counter';
+
+/**
+ * The screen, and it is an ordinary Gesso component.
+ *
+ * Nothing here knows it is in a native window. `ctx.channel` gives a
+ * replica of something the main process serves: `view` is a set of
+ * observables that arrive as the state changes, and `send` is the
+ * typed commands going the other way. Behind them is a process
+ * boundary, and the only reason to know that is latency, because a
+ * command crossing it costs about a frame and a half.
+ *
+ * Three things are worth knowing before you change them.
+ *
+ *   - The component body runs once. Nothing re-runs when the count
+ *     changes: `text` is bound to an observable, so one property on
+ *     one node is written and the next frame is drawn from it.
+ *   - No colour here is a hex value. `background`, `primary` and
+ *     `textMuted` are names looked up on whichever theme the node
+ *     inherits, and the root below provides that theme from the
+ *     appearance the shell reports. The framework carries the
+ *     appearance and has no opinion about what dark looks like, so
+ *     without the `theme` line the switch would replicate a value that
+ *     changed nothing on screen. `lightTheme` and `darkTheme` are a
+ *     starting point; a palette of your own answers the same names.
+ *   - The elements are lowercase because they are intrinsic, resolved
+ *     by `jsxImportSource` in `tsconfig.json` the way `<div>` needs no
+ *     import in React. `Switch` is capitalised because it is a
+ *     component from `gesso-components`, imported like any value.
+ */
+export function App(_inputs: Inputs<{}>, ctx: ComponentContext) {
+  const counter = ctx.channel(Counter);
+  const windows = ctx.channel(DesktopWindows);
+  // The scheme is what the main process told this window (see
+  // `src/view/main.ts`), so every window is in the same appearance.
+  const theme = ctx.inject(ShellService).colorScheme.pipe(map(scheme => (scheme === 'dark' ? darkTheme : lightTheme)));
+
+  return (
+    <column
+      theme={theme}
+      textStyle={theme.pipe(map(value => value.typography.body))}
+      gap={16}
+      x="center"
+      y="center"
+      width={percent(100)}
+      height={percent(100)}
+      backgroundColor="background">
+      <text text={counter.view.count.pipe(map(String))} fontSize={56} />
+
+      <row gap={10} y="center">
+        <button
+          label="Count"
+          onClick={() => counter.send.increment(1)}
+          padding={10}
+          borderRadius={8}
+          backgroundColor="primary"
+          cursor="pointer">
+          <text text="Count" color="background" fontSize={14} />
+        </button>
+
+        {/*
+          A window opening a window, over a channel rather than an
+          import: the screen asks for one and the main process makes
+          it. The new window shows the current count immediately,
+          because it replicates the same source rather than being
+          handed a copy.
+        */}
+        <button
+          label="New window"
+          onClick={() => windows.send.open()}
+          padding={10}
+          borderRadius={8}
+          backgroundColor="surface"
+          cursor="pointer">
+          <text text="New window" fontSize={14} />
+        </button>
+      </row>
+
+      <text
+        text={windows.view.count.pipe(map(open => (open === 1 ? 'One window' : `${open} windows, one source`)))}
+        fontSize={12}
+        color="textMuted"
+      />
+
+      {/*
+        The appearance is the main process's, not this window's, so
+        flipping it here changes every window that is open. That is the
+        desktop shape of `setColorScheme`: one setting, replicated.
+      */}
+      <Switch label="Dark" checked={counter.view.dark} onChange={next => counter.send.setDark(next)} />
+    </column>
+  );
+}

package/templates/electrobun/src/shared/Counter.ts

@@ -0,0 +1,28 @@
+/**
+ * The channel the main process serves and every window replicates.
+ *
+ * Declared once and imported by both sides, which is the whole of what
+ * they share: a token, the keys a window can see, the commands it can
+ * send, and no framework type above it. Nothing in here is anything
+ * but plain data, because plain data is all that crosses a channel.
+ */
+import { channel } from 'gesso-framework';
+
+export interface CounterView {
+  /** The application's whole state, and it lives in the main process. */
+  count: number;
+  /** Which appearance every window is in. One setting, all windows. */
+  dark: boolean;
+}
+
+export interface CounterCommands {
+  increment: (by: number) => void;
+  setDark: (dark: boolean) => void;
+}
+
+/**
+ * The name is the application's own, and both sides have to agree on
+ * it. The second argument is what a window shows before the main
+ * process has answered, which on a desktop is a few milliseconds.
+ */
+export const Counter = channel<CounterView, CounterCommands>('counter', { count: 0, dark: true });

package/templates/electrobun/src/shared/rpc.ts

@@ -0,0 +1,22 @@
+/**
+ * The one message a window and the main process exchange.
+ *
+ * Every channel, every patch and every command is carried inside
+ * `gessoFrame`, so this type does not grow as the application does. It
+ * is a `message` rather than a `request` on purpose: a patch expects no
+ * answer and a command expects no answer, and a request would put a
+ * timeout on a stream that runs for the life of the window.
+ */
+import type { GessoFrame } from 'gesso-electrobun';
+import type { RPCSchema } from 'electrobun/view';
+
+export type GessoWindowRPC = {
+  bun: RPCSchema<{
+    requests: Record<string, never>;
+    messages: { gessoFrame: GessoFrame };
+  }>;
+  webview: RPCSchema<{
+    requests: Record<string, never>;
+    messages: { gessoFrame: GessoFrame };
+  }>;
+};

package/templates/electrobun/src/view/index.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{name}}</title>
+    <style>
+      /*
+        The canvas is sized to its host, so the host needs a size. This
+        is the whole of the CSS a Gesso window needs; everything else
+        in it is painted, not styled. The background is here so that
+        the moment before the first frame is not a white flash on a
+        dark desktop.
+      */
+      html,
+      body {
+        margin: 0;
+        height: 100%;
+        background: #14161a;
+      }
+      #app {
+        width: 100vw;
+        height: 100vh;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>

package/templates/electrobun/src/view/main.ts

@@ -0,0 +1,53 @@
+/**
+ * The window's main thread, and its whole job.
+ *
+ * It builds the bridge to the main process, hands it to the shell as
+ * the application layer, and mounts. Every patch goes from the main
+ * process straight into the render worker as a body this thread
+ * carries and never reads, which is what keeps a webview's main thread
+ * a transport rather than a router.
+ */
+import type { GessoFrame } from 'gesso-electrobun';
+import { createElectrobunBridge } from 'gesso-electrobun/view';
+import { createApp } from 'gesso-framework';
+import { Electroview } from 'electrobun/view';
+
+import type { GessoWindowRPC } from '../shared/rpc';
+
+const bridge = createElectrobunBridge({
+  send: frame => view.rpc?.send.gessoFrame(frame),
+  // The main process is the only side that knows, so the shell is told
+  // rather than left to ask `matchMedia`, which lies in this webview.
+  onColorScheme: scheme => shell.setColorScheme(scheme)
+});
+
+const rpc = Electroview.defineRPC<GessoWindowRPC>({
+  maxRequestTime: 30_000,
+  handlers: {
+    requests: {},
+    messages: { gessoFrame: (frame: GessoFrame) => bridge.receive(frame) }
+  }
+});
+const view = new Electroview({ rpc });
+
+const host = document.getElementById('app');
+if (host === null) {
+  throw new Error('index.html has no #app element to mount into.');
+}
+
+const shell = createApp({
+  // Written out literally, and it has to be: a bundler emits a chunk
+  // for a worker it can see constructed, and cannot see through a
+  // variable holding the URL.
+  renderWorker: () => new Worker(new URL('./render.worker.ts', import.meta.url), { type: 'module' }),
+  // The application layer is in another process, so this is the bridge
+  // rather than a data worker. The render worker cannot tell.
+  appLogicWorker: bridge.endpoint,
+  // A window has no address bar, so its routes are its own.
+  history: { mode: 'memory' },
+  // A link in a desktop application belongs in the person's browser,
+  // which only the process outside this window can reach.
+  onOpenUrl: url => bridge.openUrl(url),
+  onError: (message, stack, source) => console.error(`[gesso ${source}] ${message}`, stack)
+});
+shell.mount(host);