gesso-framework 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# gesso-framework
+
+## 0.1.0
+
+First public release.
+
+Components, cells, the frame runtime, channels, routing and the worker
+barrier.
+
+A component body runs once and an `Observable` binds straight into the
+retained graph, so there is no re-render pass, no virtual DOM diff and no
+`useEffect`. An application is three files across three threads joined by one
+contract module: `channel()` names the shapes, `serveChannels` serves them
+from the application worker, `renderRoot` draws on the render worker, and
+`createApp` on the main thread spawns both and then holds neither end.
+
+`createApp(App).mountSync('#app')` runs the same contract in a single thread,
+for tests, headless rendering and environments without `OffscreenCanvas`.
+
+**The accessibility mirror.** The shell writes the semantics tree into an
+off-screen DOM over the canvas, so a screen reader, an OS accessibility API or
+an automated testing tool sees real elements where before it saw one empty
+canvas. On by default in both configurations; `accessibility: false` opts out.
+Presses, focus moves and value sets come back as ordinary input.
+
+**Failures reach the shell.** `renderRoot` listens for `error` and
+`unhandledrejection` on the worker global, so a component that throws during a
+frame is reported rather than lost; `UiInputDispatcher.onListenerError` reports
+the exceptions it has to swallow, so an `onClick` that throws is no longer
+logged only to a worker console. The protocol's `error` carries a `source` of
+`message`, `uncaught`, `renderer`, `channel` or `listener`.
+
+Entry points: the root, `/worker`, `/jsx-runtime`, `/jsx-dev-runtime` and
+`/testing`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Baker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# gesso-framework
+
+Components, cells, the frame runtime, channels, routing and the worker barrier, over [`gesso-core`](https://github.com/kevinpbaker/gesso/tree/main/packages/core).
+
+```bash
+npm install gesso-core gesso-framework rxjs
+```
+
+## An application is three files
+
+One shared module holds names and shapes and no implementation:
+
+```ts
+// notes.contract.ts
+import { channel } from 'gesso-framework';
+
+export const Notes = channel<NotesView, NotesCommands>('notes', { rows: [], open: null });
+```
+
+Your application, on its own worker. Below `serveChannels` there is no framework import in the dependency graph, so every layer beneath it is testable with bare Vitest, in node, with no browser:
+
+```ts
+// notes.app.worker.ts
+import { serveChannels } from 'gesso-framework';
+
+serveChannels([
+  {
+    token: Notes,
+    source: {
+      view: { rows: view.rows, open: view.open },
+      commands: { open: id => domain.select(id), create: () => domain.create() }
+    }
+  }
+]);
+```
+
+Everything the person sees, on the render worker:
+
+```tsx
+// notes.render.worker.ts
+import { renderRoot } from 'gesso-framework';
+
+function NotesApp(inputs, ctx) {
+  const notes = ctx.channel(Notes);
+  return (
+    <column gap={12} padding={24}>
+      <button onClick={() => notes.send.create()} padding={8}>
+        <text text="New note" />
+      </button>
+    </column>
+  );
+}
+
+renderRoot(NotesApp).useChannel(Notes);
+```
+
+And the main thread's entire job:
+
+```ts
+// main.ts
+createApp({
+  renderWorker: () => new Worker(new URL('./notes.render.worker.ts', import.meta.url), { type: 'module' }),
+  appLogicWorker: () => new Worker(new URL('./notes.app.worker.ts', import.meta.url), { type: 'module' })
+}).mount('#app');
+```
+
+The shell spawns both workers, joins them with one `MessageChannel`, hands each an end, and then holds neither. It cannot be in a patch's way even by accident.
+
+## What is not there
+
+A component body runs **once**, and an `Observable` binds straight into the retained graph. So there is no re-render pass, no virtual DOM diff, no `useEffect`, and no base class to extend for your state. Component identity _is_ node identity, so there is no second reconciler.
+
+Single-thread mode exists for tests, headless rendering and environments without `OffscreenCanvas`: `createApp(NotesApp).useChannel(Notes, { source }).mountSync('#app')`. Channels resolve in-process there, so the same contract runs with no ports.
+
+## Entry points
+
+- `gesso-framework` -- components, cells, the runtime, routing, channels
+- `gesso-framework/worker` -- what a render or application worker imports
+- `gesso-framework/jsx-runtime`, `/jsx-dev-runtime` -- set `jsxImportSource` to `gesso-framework`
+- `gesso-framework/testing` -- the doubles its own suite uses
+
+## Documentation
+
+[Your first component](https://github.com/kevinpbaker/gesso/blob/main/apps/docs/guide/counter.md) | [Components run once](https://github.com/kevinpbaker/gesso/blob/main/apps/docs/guide/components-run-once.md) | [Cells and bindings](https://github.com/kevinpbaker/gesso/blob/main/apps/docs/guide/cells-and-bindings.md) | [Channels and the barrier](https://github.com/kevinpbaker/gesso/blob/main/apps/docs/structure/channels-and-the-barrier.md) | [Routing](https://github.com/kevinpbaker/gesso/blob/main/apps/docs/structure/routing.md)
+
+MIT (c) Kevin Baker