create-gesso-app 0.1.0

package/templates/electrobun/src/view/render.worker.ts

@@ -0,0 +1,15 @@
+/**
+ * The render worker: components, layout, paint and hit testing.
+ *
+ * It attaches to its channels by name and never learns that the other
+ * end of them is in another process. The same file in a web
+ * application says the same thing; only what is behind the channel
+ * changes.
+ */
+import { DesktopWindows } from 'gesso-electrobun/desktop';
+import { renderRoot } from 'gesso-framework';
+
+import { App } from '../render/App';
+import { Counter } from '../shared/Counter';
+
+renderRoot(App).useChannel(Counter).useChannel(DesktopWindows);

package/templates/electrobun/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  /*
+    Written by `hutch electrobun prepare`. It is what makes
+    `electrobun/main` and `electrobun/view` resolve, so a typecheck run
+    before the first prepare has nothing to resolve them against.
+  */
+  "extends": "./.hutch/devkit/tsconfig.json",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "lib": ["ES2023", "DOM", "DOM.Iterable", "WebWorker"],
+    "types": ["@types/bun"],
+
+    /* The Gesso packages ship `exports` maps, so this is the line that has to be right. */
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+
+    /* The two lines that let you write elements as markup. */
+    "jsx": "react-jsx",
+    "jsxImportSource": "gesso-framework"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "build"]
+}

package/templates/electrobun/vite.config.ts

@@ -0,0 +1,32 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'vite';
+
+import { electrobunViteAliases } from './.hutch/devkit/api/config/electrobun-vite';
+
+/**
+ * The window's assets: an ordinary Vite build with one alias list.
+ *
+ * The aliases are for Electrobun and not for Gesso. `electrobun/view`
+ * is projected into `.hutch/devkit` by `hutch electrobun prepare`
+ * rather than installed, so Vite has to be told where it went; the
+ * Gesso packages are ordinary dependencies and need nothing. This file
+ * therefore cannot be loaded before the first prepare, which is why
+ * every script in `hutch.config.ts` runs prepare first.
+ *
+ * `root` is the view, so `src/main` is never built here: the main
+ * process is Electrobun's to bundle, out of `electrobun.config.ts`.
+ * The render worker needs no configuration at all, because
+ * `new Worker(new URL(...))` is an expression Vite already splits into
+ * its own chunk.
+ */
+export default defineConfig({
+  resolve: {
+    // Spread rather than passed through, so an alias of your own has
+    // somewhere obvious to go.
+    alias: [...electrobunViteAliases(resolve(__dirname, '.hutch/devkit'))]
+  },
+  esbuild: { jsx: 'automatic', jsxImportSource: 'gesso-framework' },
+  root: 'src/view',
+  build: { outDir: '../../dist', emptyOutDir: true },
+  server: { port: 5173, strictPort: true }
+});

package/templates/web/README.md

@@ -0,0 +1,88 @@
+# {{name}}
+
+A Gesso application. The interface is built, laid out, painted and
+hit-tested in a render worker; the page's own thread creates the canvas,
+forwards input and does nothing else.
+
+```bash
+pnpm install    # or npm install
+pnpm dev
+```
+
+Then `pnpm build` for a production bundle, `pnpm preview` to serve it,
+and `pnpm typecheck` to check the types without building.
+
+## The three files
+
+| File            | What it is                                               |
+| --------------- | -------------------------------------------------------- |
+| `src/main.ts`   | The main thread: create the app and mount it into `#app` |
+| `src/worker.ts` | The render worker: name the root component               |
+| `src/App.tsx`   | The screen                                               |
+
+There are three rather than two because a component cannot cross
+`postMessage`, so the root has to be named on the worker's side of the
+barrier.
+
+`main.ts` names no worker, and that is `gesso-vite-plugin` in
+`vite.config.ts`. It finds `worker.ts` beside `main.ts` and writes the
+construction, which has to be written out as a literal because a bundler
+emits a chunk for a worker it can see constructed and cannot see through
+a variable holding the URL. The plugin also, while the dev server is
+running:
+
+- replaces the screen when you save `App.tsx`, instead of reloading the
+  page, and puts the keyboard focus back where it was;
+- draws what the render worker threw over the application that was
+  running when it threw it, source-mapped, with the node named as a path
+  through your components rather than as an id;
+- says so when a save is about to reload the page, which happens when a
+  module is reachable from the main thread as well as from the worker.
+
+If you would rather say it out loud, write it and the plugin leaves the
+construction alone:
+
+```ts
+createApp({
+  renderWorker: () => new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' })
+});
+```
+
+```json
+"jsx": "react-jsx",
+"jsxImportSource": "gesso-framework"
+```
+
+Those two lines in `tsconfig.json` are the whole of what makes `<row>`
+and `<text>` work. JSX here is a spelling rather than a runtime: it
+compiles onto the element factories and produces the identical tree, so
+`Row({ gap: 8 }, Text({ text: 'Ready' }))` is the same thing written the
+other way.
+
+## Reporting errors from a production build
+
+The overlay is a development tool and a production build carries no
+reference to it. What a shipped application wants instead is its own
+`onError`, which takes the same three arguments:
+
+```ts
+createApp({
+  onError: (message, stack, source) => {
+    reportToYourService({ message, stack, source });
+  }
+});
+```
+
+`source` is one of `message`, `uncaught`, `renderer`, `listener` or
+`channel`, and it says what the failure cost: a `listener` error means
+one handler did not run, a `renderer` error means the surface stopped
+being updated, and a `channel` error means the data behind an intact
+view has stopped arriving.
+
+## Where to go next
+
+- `App.tsx` is commented with what each part of it is doing.
+- `gesso-components` has the controls: inputs, overlays, structure,
+  data and media. `Switch` in `App.tsx` is one of them.
+- Every prop takes a value or an Observable of that value. That is the
+  whole binding model, and it is why the component body runs once.

package/templates/web/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.local
+.DS_Store

package/templates/web/index.html

@@ -0,0 +1,28 @@
+<!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 application needs; everything
+        else on the page is painted, not styled.
+      */
+      html,
+      body {
+        margin: 0;
+        height: 100%;
+      }
+      #app {
+        width: 100vw;
+        height: 100vh;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/web/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "gesso-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "gesso-components": "^0.1.0",
+    "gesso-core": "^0.1.0",
+    "gesso-framework": "^0.1.0",
+    "rxjs": "^7.8.2"
+  },
+  "devDependencies": {
+    "gesso-devtools": "^0.1.0",
+    "gesso-vite-plugin": "^0.1.0",
+    "typescript": "~7.0.2",
+    "vite": "^8.2.0"
+  }
+}

package/templates/web/src/App.tsx

@@ -0,0 +1,63 @@
+import { map } from 'rxjs/operators';
+
+import { percent } from 'gesso-core';
+import { Switch } from 'gesso-components';
+import { internalState, type ComponentContext, type Inputs } from 'gesso-framework';
+
+/**
+ * The screen.
+ *
+ * A Gesso component is a function that runs once. What it returns is a
+ * tree of nodes that stays: nothing here re-runs when the count
+ * changes, because `text` is bound to an Observable, so one property on
+ * one node is written and the next frame is drawn from it.
+ *
+ * Three things are worth knowing before you change them.
+ *
+ *   - `internalState(0)` is state this component owns. Writing
+ *     `count.value++` marks exactly the bindings that read it, and
+ *     nothing else.
+ *   - A bound property costs what it touches. `text` is content and
+ *     `opacity` is paint, so neither re-runs layout; a bound `width` or
+ *     `gap` would.
+ *   - No colour here is a hex value. `primary`, `background` and
+ *     `textMuted` are names looked up on whichever theme the node
+ *     inherits, so this screen follows a theme it never mentions.
+ *
+ * The elements are lowercase because they are intrinsic, resolved by
+ * `jsxImportSource` in `tsconfig.json`, the same way `<div>` needs no
+ * import in React. `Switch` is capitalised because it is a component
+ * from `gesso-components`, so it is imported like any other value.
+ */
+export function App(_inputs: Inputs<{}>, _context: ComponentContext) {
+  const count = internalState(0);
+  const hinted = internalState(true);
+
+  return (
+    <column gap={16} x="center" y="center" width={percent(100)} height={percent(100)} backgroundColor="background">
+      <text text="Hello from a render worker" fontSize={22} fontWeight="bold" />
+
+      <row gap={12} y="center">
+        <text text={count.pipe(map(value => `Clicks: ${value}`))} fontSize={16} />
+        <button
+          label="Add one"
+          onClick={() => count.value++}
+          padding={8}
+          borderRadius={6}
+          backgroundColor="primary"
+          cursor="pointer">
+          <text text="+1" color="background" fontSize={14} />
+        </button>
+      </row>
+
+      <text
+        text={count.pipe(map(value => (value === 0 ? 'Press the button.' : 'Nothing was rebuilt to do that.')))}
+        fontSize={12}
+        color="textMuted"
+        opacity={hinted.pipe(map(showing => (showing ? 1 : 0)))}
+      />
+
+      <Switch label="Show the hint" checked={hinted} onChange={next => (hinted.value = next)} />
+    </column>
+  );
+}

package/templates/web/src/main.ts

@@ -0,0 +1,31 @@
+/**
+ * The main thread's entire job.
+ *
+ * It finds a host element, creates the app and mounts. Everything a
+ * person sees is built, laid out, painted and hit-tested in the worker;
+ * the page forwards input events and does nothing else, so work on this
+ * thread cannot delay a frame.
+ *
+ * The worker is not named here. `gesso-vite-plugin`, in
+ * `vite.config.ts`, finds `worker.ts` beside this file and writes the
+ * `new Worker(new URL(...))` construction, which is the only form a
+ * bundler emits a chunk for. It also draws the error overlay over the
+ * app when the worker throws, and gives the worker its hot-replacement
+ * wiring, so saving `App.tsx` redraws the screen without reloading the
+ * page. If you would rather say it out loud, write it and the plugin
+ * leaves it alone:
+ *
+ *   createApp({
+ *     renderWorker: () => new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' })
+ *   });
+ */
+import { createApp } from 'gesso-framework';
+
+const host = document.querySelector<HTMLElement>('#app');
+if (host === null) {
+  throw new Error('index.html has no #app element to mount into.');
+}
+
+const app = createApp();
+
+app.mount(host);

package/templates/web/src/worker.ts

@@ -0,0 +1,12 @@
+/**
+ * The render worker: everything the person sees.
+ *
+ * A component cannot cross `postMessage`, so the root is named here
+ * rather than passed in from `main.ts`. That one constraint is the
+ * only reason this file exists, and it is why every Gesso application
+ * has three files rather than two.
+ */
+import { renderRoot } from 'gesso-framework';
+import { App } from './App';
+
+renderRoot(App);

package/templates/web/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "module": "esnext",
+    "lib": ["ES2023", "DOM"],
+    "types": ["vite/client"],
+
+    /* The packages ship `exports` maps, so this is the line that has to be right. */
+    "moduleResolution": "bundler",
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "strict": true,
+    "noEmit": true,
+
+    /* The two lines that let you write elements as markup. */
+    "jsx": "react-jsx",
+    "jsxImportSource": "gesso-framework"
+  },
+  "include": ["src"]
+}

package/templates/web/vite.config.ts

@@ -0,0 +1,23 @@
+import { gesso } from 'gesso-vite-plugin';
+import { defineConfig } from 'vite';
+
+/**
+ * An ordinary Vite project with one Gesso plugin.
+ *
+ * The plugin writes the three things every Gesso application would
+ * otherwise write the same way by hand: the `new Worker(new URL(...))`
+ * construction for the render worker, the `import.meta.hot.accept`
+ * wiring that replaces the screen on a save instead of reloading the
+ * page, and the error overlay that draws what the worker threw over
+ * the application that was running when it threw it. The last two are
+ * development only; a production build carries no reference to
+ * `gesso-devtools` at all.
+ *
+ * None of it is required. Write `renderWorker` in `createApp` yourself
+ * and the plugin leaves the construction alone; take the plugin out
+ * altogether and the application still runs, with the incantations
+ * back in `main.ts`.
+ */
+export default defineConfig({
+  plugins: [gesso()]
+});