@hearthscale/app 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Simon Wagenfuehrer
+
+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.
+
+The fonts in `dist/fonts` are licensed under the SIL Open Font License 1.1
+(`dist/fonts/OFL.txt`). The Remix Icon font in `dist/remixicon` is licensed
+under the Apache License 2.0 (`dist/remixicon/License`).

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# @hearthscale/app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 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
+```
+
+Type-check a backend with `"lib": ["ES2022", "DOM"]`: `AppContext.signal`
+is an `AbortSignal` and `models.complete` answers an `AsyncIterable`. That
+library also declares `fetch` and `URL`, which the backend's engine does not
+have; a backend reaches the network with `ctx.net`. The manifest's schema is
+`https://hearthscale.com/app.schema.json`.
+
+A view draws with the UI kit, `@hearthscale/app-ui` beside this package:
+the tokens, the `hs-*` classes, React parts and the Remix Icon font the host
+loads into every view.
+
+A view calls the methods every view may call (`ViewHostMethods`), the
+`hearthscale/*` extensions and `openai/files/open` (`ViewExtensionMethods`)
+as requests of its MCP Apps `App`, and hears the host's notifications
+(`HostSlotNotification`, `ViewExtensionNotification`) on
+`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. `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):
+
+```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 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.
+A view that fills a tab names it with `hearthscale/ui/set-tab`
+(`{ title?, icon? }`, the icon a picture as a `data:` address); null gives
+back the surface's own title or mark, and the tab keeps the name through a
+restart.
+
+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 }`, `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/ui/cover`), so a
+menu the view opens draws over the page and the page shows through where
+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, 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
+person its ticket to pass on; `hearthscale/peers/join` asks the person for
+a ticket in a sheet the shell draws, so the view never names one. Both
+need a click. The view and the backend (`ctx.peers`) then send messages,
+JSON of at most 64 KiB, to the room's other members, hear
+theirs (`hearthscale/peers/message`, `ctx.peers.on('message')`) and leave.
+A room carries only these messages: no file, process or credential of
+either platform. It ends for everyone when the computer that opened it
+leaves. A member keeps its place and joins again on its own after a drop
+or a restart; no message is kept.
+
+## Traps
+
+- The channel carries JSON only. Bytes cross as base64 inside the host;
+  the context's `assets` and `net` methods hide that, but a tool body
+  that returns a `Uint8Array` returns nothing useful: publish it as an
+  asset and answer the id.
+- `App.request` checks a result against the schema it is given, and drops
+  every field the schema does not name unless the schema keeps them.
+  `McpUiMessageResultSchema` keeps every field, so an extension's result
+  arrives whole.