@hearthscale/app 0.1.0 → 0.2.0

package/README.md

@@ -4,9 +4,11 @@ The types an app imports: its manifest, `app.json` (`Manifest`), what
 `backend.js` exports (`Backend`), what its
 tool bodies receive (`AppContext`, `ToolRun`), and the slots a view
 reserves for the shell's chat, composer, cards, live terminal and the
-tab's web page (`HostSlot`). The package carries no runtime: the app host serves `require('@hearthscale/app')` from
-itself, so a bundle with the package marked external ships nothing of the
-platform.
+tab's web page (`HostSlot`). The package carries no runtime for a
+backend: `hearthscale dev` and `hearthscale pack` bundle an import of
+`@hearthscale/app` as an empty module, so a backend ships nothing of the
+platform and imports only its types. `@hearthscale/app/view` is the one
+runtime part, which a view bundles.
 
 ```sh
 npm install --save-dev @hearthscale/app
@@ -29,17 +31,24 @@ as requests of its MCP Apps `App`, and hears the host's notifications
 `app.fallbackNotificationHandler`. `ViewHostContext` types the keys the host
 adds to the host context, and `ContentBlockMeta`, `ModelContextAnswer`,
 `MessageOptions`, `ResourceReadOptions`, `ResourceVersion` and
-`ResourcePath` the `_meta` of the standard messages. `ViewExtensionCall`
-types one call of an extension:
+`ResourcePath` the `_meta` of the standard messages. `hostCall` of
+`@hearthscale/app/view` gives one typed call of every request a view sends
+beyond MCP Apps, the host methods and the extensions alike (`HostCall`,
+over `ViewMethods`), and of the MCP Apps requests that take Hearthscale's
+own fields (`ViewStandardMethods`; `ViewCall` covers both):
 
-```js
-import { App, McpUiMessageResultSchema } from '@modelcontextprotocol/ext-apps';
-const call = (method, params) => app.request({ method, params }, McpUiMessageResultSchema);
-const { sessions } = await call('hearthscale/sessions/list', {});
+```ts
+import { App } from '@modelcontextprotocol/ext-apps';
+import { hostCall } from '@hearthscale/app/view';
+
+const app = new App({ name: 'Inbox', version: '1.0.0' }, {});
+const call = hostCall(app);
+const { sessions } = await call('hearthscale/sessions/list');
+await call('hearthscale/ui/set-tab', { title: 'Inbox' });
 ```
 
 A view keeps a JSON value for its next load with
-`hearthscale/ui/set-widget-state` (`{ state }`, at most 64 KiB as JSON) and
+`hearthscale/ui/set-widget-state` (`{ state }`, at most 65,536 UTF-16 code units as JSON text) and
 reads it back from the host context as `hearthscale/widgetState`, null
 before the first save. The host loads a view in a tab again when the tab
 comes back after the window discarded its surface, and after a restart.
@@ -52,20 +61,30 @@ A view whose app names `models` in `uses` asks the model with MCP's
 `sampling/createMessage` (text only, on the app's chat card).
 `hearthscale/ui/select-files` (`{ accept?, multiple? }`, on a click) answers
 the files the person picked, which the view reads with `resources/read`;
-`hearthscale/ui/upload-file` (`{ name, mediaType, blob }`) keeps bytes as an
-asset the view reads back as `hearthscale-asset://<asset>`.
+`hearthscale/ui/upload-file` (`{ name, mediaType, blob }`, `blob` a `Blob`)
+keeps its bytes as an asset the view reads back as
+`hearthscale-asset://<asset>`, or streamed and by byte range at the address
+`hearthscale/assetBytes` in the host context names, followed by the asset's
+id, as a `fetch` or as the source of a picture, a sound or a video.
+`ui/download-file` saves where the person picks on a click; an embedded
+resource's `blob` may be a `Blob`, which streams into the file, beside the
+text and the base64 of MCP Apps, which hold at most 64 MiB.
 
 A view that fills a tab has a web page of its tab: the shell loads it on
 the app's own partition, where it reaches only the hosts of
 `environment.network`, once the view asks for an address with
 `hearthscale/web/navigate`. The page lies over the view's `web` slot, and
-under the view while the view covers it (`hearthscale/web/cover`), so a
+under the view while the view covers it (`hearthscale/ui/cover`), so a
 menu the view opens draws over the page and the page shows through where
-the view draws nothing. The view drives the page with the other
+the view draws nothing. The same call lays the chat and the composer of the
+view's slots under it; the terminal and the cards stay above. The view drives the page with the other
 `hearthscale/web/*` methods and hears its state as `hearthscale/web/page`
 (`WebPageState`). A link the page opens in a new window opens a tab of the
-same surface. The page keeps its address through a restart, and the app's
-tools drive it through `surface.command`.
+same surface, and a popup with a size of its own opens as a window that
+keeps its opener. The keys the view names with `hearthscale/web/keys` reach
+the view as `hearthscale/web/key` while the page has the keyboard. The page
+keeps its address through a restart, and the app's tools drive it through
+`surface.command`.
 
 An app that names `peers` in `uses` talks to itself on other computers in
 rooms. A view opens a room with `hearthscale/peers/create` and shows the