@n1h/sweetview 0.0.0-stage → 0.1.1

package/docs/page.md

@@ -0,0 +1,71 @@
+# @n1h/sweetview/page
+
+The page module gives browser code a transport to the window host. It runs in the browser page inside a sweetview window. Its only import is a type from `@n1h/sweetview/ipc`, so it bundles for the browser without Bun or `bun:ffi`.
+
+```ts
+import { isWebview, webviewTransport } from "@n1h/sweetview/page";
+```
+
+## Reference
+
+### isWebview
+
+```ts
+export const isWebview = (): boolean
+```
+
+Reports whether the page is running inside a sweetview window. It checks that `window` exists and that `window.__sweetview_rpc` is a function.
+
+Returns: `true` inside a sweetview window, `false` elsewhere, including outside a browser.
+
+### webviewTransport
+
+```ts
+export function webviewTransport(): Transport
+```
+
+Creates a `Transport` for the page's sweetview window. `Transport` is documented in [ipc.md](ipc.md). Pass the result to `createBridge` for the typed surface.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `kind` | `TransportKind` | Always `"webview"`. |
+| `call(method, params)` | `Promise<unknown>` | Calls `__sweetview_rpc(method, params)`. Resolves with the result. A result of `undefined` arrives as `null`. Rejects with an `Error` whose message is the rejection value's `message` field as a string, or the value as a string when it has no `message` field. |
+| `notify(method, params)` | `void` | Sends the same call as `call` and discards the result. A failure is logged with `console.error` as `"<method> failed:"` and the message. |
+| `onEvent(fn)` | `() => void` | Registers `fn` for every event. Returns a function that removes it. |
+
+Every transport created on one page shares one set of event listeners. The first `webviewTransport()` call installs `window.__sweetview_emit`, unless the page already defined it. In that case `onEvent` listeners receive no events. Events the host emits before the first `webviewTransport()` call find no `__sweetview_emit` and are lost.
+
+Returns: a `Transport` whose `kind` is `"webview"`.
+
+Throws: `Error` with the message `"not running inside sweetview"` when `window.__sweetview_rpc` is not defined.
+
+Outside a browser, where there is no global `window`, it throws the same `Error`.
+
+Thread: the browser page.
+
+## Globals
+
+The module declares both globals as optional properties of `Window`.
+
+| Global | Type | Installed by | Meaning |
+|---|---|---|---|
+| `__sweetview_rpc` | `(method: string, params: unknown) => Promise<unknown>` | The UI thread, with `webview_bind`, in `createWebviewApp` | Sends a call to the host. A method in `uiMethods` is answered on the UI thread. Any other method goes to the worker. In a window without a worker, any other method rejects. A result of `undefined` resolves as `null`. Rejects with `{ message }` on failure. |
+| `__sweetview_emit` | `(name: string, payload: unknown) => void` | `webviewTransport()`, on its first call | The UI thread evaluates `__sweetview_emit(name, payload)` once per event. A payload of `undefined` arrives as `null`. It passes the event to every listener registered with `onEvent`. |
+
+The host side of both is in [app.md](app.md).
+
+## Example
+
+```ts
+import { createBridge } from "@n1h/sweetview/ipc";
+import { isWebview, webviewTransport } from "@n1h/sweetview/page";
+
+type Methods = { "notes.list": [void, string[]] };
+type Events = { "notes.changed": { count: number } };
+
+if (isWebview()) {
+  const bridge = createBridge<Methods, Events>(webviewTransport());
+  bridge.on("notes.changed", ({ count }) => console.log(count));
+  console.log(await bridge.rpc("notes.list"));
+}
+```

package/docs/settings-store.md

@@ -0,0 +1,125 @@
+# @n1h/sweetview/settings-store
+
+A settings file for a small app: one JSON document in the user's per-app folder, read once at start and written whole on every change. Every call is synchronous, so the UI thread can use it after `run()` has blocked it in the OS loop, and it runs on any thread and in any build or test script. It imports only `node:fs`, `node:os` and `node:path`, and loads neither `bun:ffi` nor the webview library.
+
+```ts
+import { appDataDir, createSettingsStore, type SettingsStore, type SettingsStoreOptions } from "@n1h/sweetview/settings-store";
+```
+
+## Reference
+
+### appDataDir
+
+```ts
+export function appDataDir(app: string): string
+```
+
+Returns the per-user folder an app keeps its own files in. It does not create the folder.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `app` | `string` | The app's folder name, joined onto the per-user base folder. |
+
+The base folder depends on `process.platform`:
+
+| Platform | Folder | When the variable is unset |
+|---|---|---|
+| Windows (`win32`) | `%APPDATA%\<app>` | `<home>\AppData\Roaming\<app>` |
+| macOS (`darwin`) | `~/Library/Application Support/<app>` | not applicable |
+| Linux and every other platform | `$XDG_CONFIG_HOME/<app>` | `~/.config/<app>` |
+
+Returns: the folder path. `<home>` and `~` are `os.homedir()`.
+
+Platforms: Windows / macOS / Linux: implemented, with the base folder from the table.
+
+### SettingsStoreOptions
+
+```ts
+export type SettingsStoreOptions<T> = {
+  app: string;
+  file?: string;
+  dir?: string;
+  defaults: T;
+  sanitize?: (input: unknown) => T;
+};
+```
+
+The options of `createSettingsStore`.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `app` | `string` | required | The folder name under `appDataDir`. Not used when `dir` is set. |
+| `file` | `string` | `"settings.json"` | The file name inside the folder. |
+| `dir` | `string` | `appDataDir(app)` | The folder itself, in place of the app-data folder. For tests, or an app that keeps settings elsewhere. |
+| `defaults` | `T` | required | The base of the default `sanitize`. `load()` returns a shallow copy of it when `sanitize` throws. |
+| `sanitize` | `(input: unknown) => T` | shallow merge over `defaults` | Turns whatever the file held into a valid `T`: fill gaps, clamp ranges, drop junk. Receives the parsed JSON, or `undefined` when the file is missing, cannot be read or is not valid JSON. |
+
+The default `sanitize` returns `{ ...defaults, ...input }` when `input` is a non-null object, and a shallow copy of `defaults` otherwise. The merge is one level deep: a nested object in the file replaces the default's nested object whole. Values are not type-checked. Keys that `defaults` lacks are kept. A JSON array is not an object here: it gives a copy of `defaults`.
+
+### SettingsStore
+
+```ts
+export type SettingsStore<T> = {
+  readonly path: string;
+  load(): T;
+  save(settings: T): void;
+};
+```
+
+The handle `createSettingsStore` returns.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `path` | `string` | The full path of the settings file. The file need not exist yet. |
+| `load` | `() => T` | Reads the file and returns the settings. |
+| `save` | `(settings: T) => void` | Writes the whole document. |
+
+`load()` handles each file state as follows. Logging goes to stderr through `console.error`, with `<message>` the error's message.
+
+| File state | Logged | Returns |
+|---|---|---|
+| Missing | nothing | `sanitize(undefined)`; with the default `sanitize`, a copy of `defaults` |
+| Valid JSON | nothing | `sanitize(parsed)` |
+| Not valid JSON | `settings: <path> unreadable, using defaults: <message>` | `sanitize(undefined)`, as for a missing file |
+| Cannot be read, for example no permission or a folder at the path | same as above | same as above |
+| `sanitize` throws, on any path | `settings: sanitize failed for <path>, using defaults: <message>`, after the line for the file state when there is one | a shallow copy of `defaults` |
+
+`save(settings)` creates the folder and any missing parents, then writes `JSON.stringify(settings, null, 2)` followed by a newline, as UTF-8. It writes to `<path>.<pid>.tmp` beside the file and renames that over the file, so an interrupted write leaves the previous document rather than a truncated one. It does not call `sanitize`. When creating the folder, serialising, writing or renaming fails, it deletes the temporary file, logs `settings: could not write <path>: <message>` to stderr and returns normally.
+
+Neither `load()` nor `save()` throws. Failures are logged to stderr.
+
+Thread: any thread. Both calls block the calling thread on file I/O.
+
+### createSettingsStore
+
+```ts
+export function createSettingsStore<T extends object>(options: SettingsStoreOptions<T>): SettingsStore<T>
+```
+
+Creates a store for one settings file. It touches no file at creation. The file path is `dir`, or `appDataDir(app)` when `dir` is unset, joined with `file`, or `settings.json` when `file` is unset.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `options` | `SettingsStoreOptions<T>` | required | See `SettingsStoreOptions`. |
+
+Returns: a `SettingsStore<T>` for that path.
+
+## Example
+
+```ts
+import { createSettingsStore } from "@n1h/sweetview/settings-store";
+
+type Settings = { volume: number; muted: boolean };
+const DEFAULTS: Settings = { volume: 50, muted: false };
+
+const store = createSettingsStore<Settings>({
+  app: "my-app",
+  defaults: DEFAULTS,
+  sanitize: (input) => {
+    const s = (typeof input === "object" && input !== null ? input : {}) as Partial<Settings>;
+    return { volume: typeof s.volume === "number" ? Math.min(100, Math.max(0, s.volume)) : DEFAULTS.volume, muted: s.muted === true };
+  },
+});
+let settings = store.load();
+store.save((settings = { ...settings, muted: true }));
+```

package/docs/webview-library.md

@@ -0,0 +1,104 @@
+# The webview library
+
+The library `@n1h/sweetview` runs on, and what differs from upstream webview.
+
+- Shipped by [`@n1h/sweetview-webview-bun`](https://github.com/n0t-invented-here/sweetview-webview-bun)
+  in its `build/` folder for Windows x64, macOS (universal) and Linux x64.
+- Built from https://github.com/n0t-invented-here/sweetview-webview, branch
+  `sweetview`: [webview/webview](https://github.com/webview/webview) at
+  `f1a9d6b` plus the two C API calls below.
+- The Linux arm64 file in the same folder, `libwebview-arm64.so`, is the
+  upstream build and lacks the two calls.
+
+```c
+webview_error_t webview_set_background_color(webview_t w, int r, int g, int b, int a);
+webview_error_t webview_set_asset(webview_t w, const char *path, const char *mime, const void *data, size_t len);
+```
+
+`webview_set_background_color`:
+
+- Windows: sets `ICoreWebView2Controller2::DefaultBackgroundColor`. For the
+  desktop to show through, the host window also needs composition that
+  honours alpha.
+- macOS: sets `drawsBackground` on the `WKWebView` to false when `a` is 0 and
+  to true otherwise. It makes the `NSWindow` non-opaque when `a` is below 255
+  and sets the window's background colour to the given colour.
+- Linux: accepted, does nothing.
+
+Each of `r`, `g`, `b` and `a` is 0 to 255.
+
+| Return | When |
+|---|---|
+| `WEBVIEW_ERROR_OK` (0) | Success. |
+| `WEBVIEW_ERROR_INVALID_ARGUMENT` (-2) | A component outside 0 to 255. |
+| `WEBVIEW_ERROR_INVALID_STATE` (-3) | Windows: the browser controller does not exist yet. macOS: there is no `WKWebView`. |
+| `WEBVIEW_ERROR_UNSPECIFIED` (-1) | Windows: `ICoreWebView2Controller2` is unavailable or refuses the colour. |
+
+The fork also changes `webview_set_size` on macOS: for a window passed to
+`webview_create`, it does nothing, so that window keeps its own style, size
+and position.
+
+`webview_set_asset` serves bytes at a path of the webview's own origin.
+
+- A page is loaded with `webview_navigate` instead of `webview_set_html`,
+  which Windows caps at 2 MB.
+- The page fetches scripts, styles, images and models by relative URL.
+- The bytes are copied into the library; nothing reaches the network.
+
+- `path` is the URL path without the leading `/`; leading slashes are
+  stripped. A path that needs percent-encoding is not supported.
+- A request's query string and fragment are ignored when matching.
+- `mime` is sent as the `Content-Type` header unchanged.
+- Calling again with the same path replaces the bytes. No call removes an
+  asset.
+- A request for a path with no asset gets a 404 with an empty body.
+
+| Return | When |
+|---|---|
+| `WEBVIEW_ERROR_OK` (0) | Success. |
+| `WEBVIEW_ERROR_INVALID_ARGUMENT` (-2) | `path` or `mime` is null, or `data` is null while `len` is not 0. |
+
+- Windows: origin `http://webview.localhost`. A `WebResourceRequested` filter
+  for that origin answers every request from the table with
+  `CreateWebResourceResponse` (200 with the given Content-Type, or 404).
+- macOS: origin `webview://localhost`. A `WKURLSchemeHandler` for the scheme
+  `webview` is registered on the `WKWebViewConfiguration` before the
+  `WKWebView` is created. It answers every `webview:` request from the same
+  table with an HTTP response: 200 with the given Content-Type and the byte
+  length, or 404.
+- Linux: accepted and stored, not served.
+
+`@n1h/sweetview` loads the library file the way `@n1h/sweetview-webview-bun`
+does.
+
+- `WEBVIEW_PATH` when set; otherwise `libwebview.dll`, `libwebview.dylib` or
+  `libwebview-<arch>.so` from `@n1h/sweetview-webview-bun/build/`.
+- The webview, the worker's `webview_dispatch` and the two extra calls use
+  that one file, and `bun build --compile` embeds it.
+- `createWebviewApp` looks the two symbols up at run time ([app.md](app.md)):
+
+| Situation | Behaviour |
+|---|---|
+| `transparent: true` and no `webview_set_background_color` | Logs a warning; the page stays opaque. |
+| `webview_set_background_color` returns an error | Throws `sweetview: webview_set_background_color failed (<code>)`. |
+| No `webview_set_asset` | Throws; the page cannot load without it. |
+| `webview_set_asset` returns an error | Throws `sweetview: webview_set_asset(<path>) failed (<code>)`. |
+| Asset `mime` | From the path's extension; unknown extensions get `application/octet-stream`. |
+
+## Source
+
+- Library: https://github.com/n0t-invented-here/sweetview-webview, default
+  branch `sweetview`.
+- Bindings: https://github.com/n0t-invented-here/sweetview-webview-bun,
+  default branch `sweetview`, with the library as its submodule; published as
+  `@n1h/sweetview-webview-bun`.
+- Files the change touches: `core/include/webview/api.h`, `c_api_impl.hh`,
+  `detail/engine_base.hh`, `detail/backends/win32_edge.hh`,
+  `detail/backends/cocoa_webkit.hh`, `detail/platform/windows/webview2/loader.hh`.
+
+## Rebuilding
+
+The recipes that clone the forks and build the library from them live in
+[`webview/`](../webview/README.md) in this repository. A change to the library
+reaches this package through a new `@n1h/sweetview-webview-bun` release and a
+matching bump of the `@n1h/sweetview-webview-bun` peer dependency.

package/docs/window-chrome.md

@@ -0,0 +1,221 @@
+# @n1h/sweetview/window-chrome
+
+A window chrome drawn by the page: the title bar, the minimise, maximise and close buttons and the resize handles are HTML, and the UI thread carries them out on the native window. The module has two halves joined by one method table: `windowChromeMethods` runs on the UI thread, and `windowChromeControls` and `resizeHandles` run in the browser page. Its imports from `@n1h/sweetview/ipc` and `@n1h/sweetview/native` are type-only, so it loads neither `bun:ffi` nor the webview library and a page bundle can import it.
+
+```ts
+import { resizeHandles, windowChromeControls, windowChromeMethods, type ResizeHandle, type WindowChromeControls, type WindowChromeInfo, type WindowChromeKind, type WindowChromeMethods, type WindowChromeMethodTable, type WindowChromeOptions } from "@n1h/sweetview/window-chrome";
+```
+
+## Shared types
+
+These types describe the contract between the two halves. They are usable in both environments.
+
+`ResizeEdge` comes from `@n1h/sweetview/native`, see [native.md](native.md). It is `"left" | "right" | "top" | "bottom" | "top-left" | "top-right" | "bottom-left" | "bottom-right"`.
+
+### WindowChromeKind
+
+```ts
+export type WindowChromeKind = "page" | "os";
+```
+
+Who draws the window frame. The value is only reported to the page through `window.info`; it does not change the window.
+
+| Value | Meaning |
+|---|---|
+| `"page"` | The page draws its own chrome. |
+| `"os"` | The window has an OS frame, and the page renders without its own chrome. |
+
+### WindowChromeInfo
+
+```ts
+export type WindowChromeInfo = { chrome: WindowChromeKind; maximized: boolean };
+```
+
+The answer to `window.info`.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `chrome` | `WindowChromeKind` | Who draws the frame. |
+| `maximized` | `boolean` | Windows: `true` while `window.maximize` has the window maximised; the OS's own maximised state is not read. macOS: whether the window is zoomed. |
+
+### WindowChromeMethods
+
+```ts
+export type WindowChromeMethods = {
+  "window.info": [void, WindowChromeInfo];
+  "window.drag": [void, void];
+  "window.resize": [ResizeEdge, void];
+  "window.minimize": [void, void];
+  "window.maximize": [void, void];
+  "window.close": [void, void];
+};
+```
+
+The UI-thread methods a page-drawn chrome calls, as `[params, result]` pairs. Add it to the method map `M` that `createWebviewApp` is called with: `type Methods = WindowChromeMethods & { ... }`.
+
+| Method | Params | Result | What `windowChromeMethods` does on the UI thread |
+|---|---|---|---|
+| `window.info` | `void` | `WindowChromeInfo` | Returns the configured `chrome` kind and `window.maximized()`. |
+| `window.drag` | `void` | `void` | Calls `window.startDrag()`: the window follows the cursor until the mouse button is released. Windows: the OS's own move loop runs. macOS: the drag starts from the application's current event. |
+| `window.resize` | `ResizeEdge` | `void` | Calls `window.startResize(edge)`. Windows: the edge or corner follows the cursor until the left mouse button is released. macOS: nothing happens. |
+| `window.minimize` | `void` | `void` | Calls `window.minimize()`. |
+| `window.maximize` | `void` | `void` | Calls `window.toggleMaximize()`: maximised, or back to the previous bounds when already maximised. |
+| `window.close` | `void` | `void` | Calls the `close` option. Without one, it calls `window.hide()`: the window disappears and the app keeps running. |
+
+### WindowChromeMethodTable
+
+```ts
+export type WindowChromeMethodTable = { [K in keyof WindowChromeMethods]: (params: WindowChromeMethods[K][0]) => WindowChromeMethods[K][1] };
+```
+
+One handler per method of `WindowChromeMethods`, each taking that method's params and returning its result. `windowChromeMethods` returns one.
+
+## UI thread
+
+This half runs on the UI thread, inside the process that owns the window. It answers the `window.*` calls through the `uiMethods` option of `createWebviewApp`, see [app.md](app.md). `windowChromeMethods`, `WindowChromeInfo`, `WindowChromeKind`, `WindowChromeMethods` and `WindowChromeOptions` are also exported from `@n1h/sweetview`.
+
+### WindowChromeOptions
+
+```ts
+export type WindowChromeOptions = {
+  chrome?: WindowChromeKind;
+  close?: () => void;
+};
+```
+
+The options of `windowChromeMethods`.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `chrome` | `WindowChromeKind` | `"page"` | What `window.info` reports. Pass `"os"` when the same page is hosted in a plain framed window. |
+| `close` | `() => void` | `() => window.hide()` | What `window.close` does. The default hides the window and does not quit, so a tray or a menu can show it again. Pass `app.quit` for a main window, so the close button ends the app. |
+
+### windowChromeMethods
+
+```ts
+export function windowChromeMethods(window: Overlay, options: WindowChromeOptions = {}): WindowChromeMethodTable
+```
+
+Builds the `window.*` handlers for one window. Spread the result into `uiMethods`. The table in `WindowChromeMethods` lists what each handler does.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `window` | `Overlay` | required | The window the methods act on, from `createOverlayWindow` in `@n1h/sweetview/native`, see [native.md](native.md). Create it with `transparent: true`, `topmost: false`, `hideFromTaskbar: false` and `noActivate: false` for a page-drawn chrome. |
+| `options` | `WindowChromeOptions` | `{}` | See `WindowChromeOptions`. |
+
+Returns: a `WindowChromeMethodTable` bound to `window`.
+
+Throws: on Windows, the `window.resize` handler throws `sweetnative: SetTimer failed (<code>)` when the resize timer cannot be created; `createWebviewApp` passes the message to the page as a failed call.
+
+Platforms: Windows: implemented; `window.resize` moves the edge or corner with the cursor every 10 ms, down to 160x120 window units, and `window.maximize` toggles between the primary monitor's work area and the previous bounds. macOS: implemented except `window.resize`, which is a no-op; a frameless window has no resizable style, so the user cannot resize it; `window.maximize` zooms. Linux: not available; `createOverlayWindow` throws, so there is no `Overlay` to pass.
+
+Thread: UI thread. Each handler calls the `Overlay` directly.
+
+## Page
+
+This half runs in the browser page shown in the window. It talks to the UI thread through a `Transport` from `@n1h/sweetview/ipc`, see [ipc.md](ipc.md); inside a webview window that is `webviewTransport()` from `@n1h/sweetview/page`, see [page.md](page.md). It uses no framework.
+
+### WindowChromeControls
+
+```ts
+export type WindowChromeControls = {
+  info(): Promise<WindowChromeInfo>;
+  onTitlePointerDown(event: { button: number }): void;
+  onHandlePointerDown(edge: ResizeEdge): (event: { button: number }) => void;
+  minimize(): void;
+  toggleMaximize(): void;
+  close(): void;
+};
+```
+
+What the chrome's elements call.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `info` | `() => Promise<WindowChromeInfo>` | Calls `window.info` and resolves with the answer. Tells the page whether to draw the chrome at all, and the maximised state for the restore glyph and square corners. Nothing reports later changes, so call it again after `toggleMaximize`. Rejects when the call fails. |
+| `onTitlePointerDown` | `(event: { button: number }) => void` | For the title bar's pointer-down. A primary-button press, `button` 0, sends `window.drag`. Other buttons are ignored. |
+| `onHandlePointerDown` | `(edge: ResizeEdge) => (event: { button: number }) => void` | Returns the pointer-down handler for one resize handle. A primary-button press sends `window.resize` with `edge`. Other buttons are ignored. |
+| `minimize` | `() => void` | Sends `window.minimize`. |
+| `toggleMaximize` | `() => void` | Sends `window.maximize`. |
+| `close` | `() => void` | Sends `window.close`. |
+
+Every member except `info` sends through `transport.notify` and returns without waiting. With `webviewTransport()`, a failure on the UI thread is logged to the page's console as `<method> failed: <message>`.
+
+### windowChromeControls
+
+```ts
+export function windowChromeControls(transport: Transport): WindowChromeControls
+```
+
+Builds the page-side controls over a transport.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `transport` | `Transport` | required | The page's connection to the UI thread. In a webview window, `webviewTransport()`. |
+
+Returns: a `WindowChromeControls`.
+
+Thread: browser page.
+
+### ResizeHandle
+
+```ts
+export type ResizeHandle = {
+  edge: ResizeEdge;
+  style: { top?: number; right?: number; bottom?: number; left?: number; width?: number; height?: number; cursor: string };
+};
+```
+
+The placement of one resize handle.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `edge` | `ResizeEdge` | The edge or corner the handle resizes from. Pass it to `onHandlePointerDown`. |
+| `style` | `{ top?: number; right?: number; bottom?: number; left?: number; width?: number; height?: number; cursor: string }` | Placement inside the window in CSS pixels, plus the CSS cursor. It holds no `position`; add `position: "absolute"`. |
+
+### resizeHandles
+
+```ts
+export function resizeHandles(thickness = 6): ResizeHandle[]
+```
+
+Returns the eight resize handles along the window's edges: four edge strips `thickness` CSS pixels wide and four corner squares twice that. Lay them over the page, and hide them while the window is maximised.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `thickness` | `number` | `6` | The strip width in CSS pixels. Corners are `2 * thickness` square. |
+
+Returns: the handles in this order, with `t` the thickness and `c` twice it:
+
+| `edge` | Placement | Size | `cursor` |
+|---|---|---|---|
+| `top` | `top: 0`, `left: t`, `right: t` | `height: t` | `ns-resize` |
+| `bottom` | `bottom: 0`, `left: t`, `right: t` | `height: t` | `ns-resize` |
+| `left` | `left: 0`, `top: t`, `bottom: t` | `width: t` | `ew-resize` |
+| `right` | `right: 0`, `top: t`, `bottom: t` | `width: t` | `ew-resize` |
+| `top-left` | `top: 0`, `left: 0` | `width: c`, `height: c` | `nwse-resize` |
+| `bottom-right` | `bottom: 0`, `right: 0` | `width: c`, `height: c` | `nwse-resize` |
+| `top-right` | `top: 0`, `right: 0` | `width: c`, `height: c` | `nesw-resize` |
+| `bottom-left` | `bottom: 0`, `left: 0` | `width: c`, `height: c` | `nesw-resize` |
+
+## Example
+
+Page side, without a framework:
+
+```ts
+import { webviewTransport } from "@n1h/sweetview/page";
+import { resizeHandles, windowChromeControls } from "@n1h/sweetview/window-chrome";
+
+const chrome = windowChromeControls(webviewTransport());
+const info = await chrome.info();
+if (info.chrome === "page") {
+  document.getElementById("title-bar")?.addEventListener("pointerdown", chrome.onTitlePointerDown);
+  document.getElementById("close")?.addEventListener("click", () => chrome.close());
+  for (const h of info.maximized ? [] : resizeHandles()) {
+    const el = document.body.appendChild(document.createElement("div"));
+    el.style.position = "absolute";
+    for (const [key, value] of Object.entries(h.style)) el.style.setProperty(key, `${value}${typeof value === "number" ? "px" : ""}`);
+    el.addEventListener("pointerdown", chrome.onHandlePointerDown(h.edge));
+  }
+}
+```

package/docs/worker.md

@@ -0,0 +1,72 @@
+# @n1h/sweetview/worker
+
+The worker module hosts the app's Service behind a sweetview window. It runs inside the Bun Worker that `createWebviewApp` starts from its `worker` option, described in [app.md](app.md). The worker owns the Bun event loop while the UI thread is blocked in the OS loop.
+
+```ts
+import { hostService } from "@n1h/sweetview/worker";
+```
+
+## Reference
+
+### hostService
+
+```ts
+export function hostService<M extends MethodMap, E extends EventMap>(service: Service<M, E>): void
+```
+
+Connects `service` to the window that started this worker. It subscribes to the Service's events and sets `self.onmessage`, replacing any handler already there, then returns.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `service` | `Service<M, E>` | required | The Service to host. `Service`, `MethodMap` and `EventMap` are documented in [ipc.md](ipc.md). |
+
+Thread: the Bun Worker started by `createWebviewApp`. Call once, at the top level of the worker entry. Writing a frame blocks the worker while the ring is full.
+
+#### Messages from the UI thread
+
+The UI thread posts two kinds of message:
+
+| Message | Shape | Effect |
+|---|---|---|
+| init | `{ kind: "init"; ring: SharedArrayBuffer; webviewHandle: number; drainCallbackPtr: number; libPath: string }` | Sent once, before any call. The worker wraps `ring`, opens the webview library at `libPath`, and writes any frames produced before this message; a frame that cannot be written is logged to the worker console and the rest still go. When `dlopen` fails, the worker throws and the UI thread logs `sweetview: the worker failed: <message>`. |
+| call | `{ kind: "call"; seq: string \| null; method: string; params: unknown }` | Runs `service.call(method, params, ctx)`. A `seq` of `null` means no reply is sent. |
+
+Every call gets the same `ctx`: `{ session: { id: "webview", kind: "webview" } }`. One window is one session.
+
+The worker opens the library with `dlopen` and binds one symbol, `webview_dispatch`. The UI thread runs the OS loop and does not process Bun messages. The worker wakes it with `webview_dispatch`, which queues the UI thread's drain callback on that loop. The worker does not import `@n1h/sweetview-webview-bun`. `libPath` is the library the UI thread loaded, so both threads use the same file.
+
+#### Replies and events
+
+Replies and events go back to the UI thread as JSON frames in the shared ring. After writing a frame, the worker calls `webview_dispatch` only when no wakeup is already pending, so a burst of frames costs one dispatch.
+
+| Outcome | Frame sent |
+|---|---|
+| `service.call` resolves, `seq` set | `{ kind: "reply", seq, ok: true, result }` |
+| `service.call` rejects, `seq` set | `{ kind: "reply", seq, ok: false, error }`, where `error` is the error's `message`, or `String(err)` for a non-`Error` value. |
+| `service.call` rejects, `seq` is `null` | None. The worker logs `"<method> failed:"` and the message with `console.error`. |
+| the Service emits with no `to`, or `to` equal to `"webview"` | `{ kind: "event", name, payload }` |
+| the Service emits with any other `to` | None. The event is dropped. |
+
+`hostService` never calls the Service's `endSession` or `dispose`. The UI thread terminates the worker when `run()` returns, or when `createWebviewApp` throws after starting it.
+
+Writing a frame blocks the worker while the ring is full, until the UI thread drains it. A frame whose UTF-8 JSON is longer than the ring's capacity minus 4 bytes throws `RangeError`. A result or payload that `JSON.stringify` rejects, such as a `BigInt`, throws `TypeError`. For a call with a `seq`, either error becomes an error reply. For an event emitted after the init message, it is thrown out of the Service's emit call. The capacity is `ringBytes` in [app.md](app.md).
+
+## Example
+
+```ts
+import { defineService } from "@n1h/sweetview/ipc";
+import { hostService } from "@n1h/sweetview/worker";
+
+type Methods = { "notes.list": [void, string[]] };
+type Events = { "notes.changed": { count: number } };
+
+const service = defineService<Methods, Events>((emit) => ({
+  methods: {
+    "notes.list": () => {
+      emit("notes.changed", { count: 0 });
+      return [];
+    },
+  },
+}));
+hostService(service);
+```

package/file-imports.d.ts

@@ -0,0 +1,19 @@
+// Types for the page files an app imports by path:
+//
+//   import js from "./build/frontend/main.js" with { type: "file" };
+//
+// The import resolves to a path the file can be read from (`Bun.file(js)` is
+// the asset), and `bun build --compile` embeds the file. Pull these in from
+// a .d.ts of the app's own:
+//
+//   /// <reference types="@n1h/sweetview/file-imports" />
+//
+// and declare the app's other file kinds (models, images) beside it.
+declare module "*.css" {
+  const path: string;
+  export default path;
+}
+declare module "*.js" {
+  const path: string;
+  export default path;
+}