@fungi.computer/agar 0.0.0-stage → 0.0.1

package/docs/api/query.md

@@ -0,0 +1,253 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+[@fungi.computer/agar](modules.md) / query
+
+# query
+
+## Type Aliases
+
+### FeedSnapshot
+
+```ts
+type FeedSnapshot<T> =
+  | Readonly<{
+      status: "live";
+      data: T;
+    }>
+  | Readonly<{
+      status: "loading" | "error";
+      data?: T;
+    }>;
+```
+
+A feed can lose its connection without losing its last owner snapshot.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+---
+
+### FeedWatch
+
+```ts
+type FeedWatch<T> = (onChange, signal) => Disposer | Promise<Disposer>;
+```
+
+Start a live feed, calling `onChange` with each snapshot until `signal` aborts;
+the returned (or resolved) Disposer tears it down.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+#### Parameters
+
+| Parameter  | Type                   |
+| ---------- | ---------------------- |
+| `onChange` | (`snapshot`) => `void` |
+| `signal`   | `AbortSignal`          |
+
+#### Returns
+
+\| [`Disposer`](index.md#disposer) \|
+`Promise`\<[`Disposer`](index.md#disposer)\>
+
+---
+
+### QueryApp
+
+```ts
+type QueryApp = Pick<AppRoot, "identity" | "context" | "capabilities">;
+```
+
+The App-owned identity and grants needed by the query integration.
+
+## Variables
+
+### queryKeys
+
+```ts
+const queryKeys: object;
+```
+
+Cache identity belongs to an App surface and its selected Computer.
+
+#### Type Declaration
+
+| Name   | Type                                                                                  | Description                                                                                                          |
+| ------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `of()` | (`app`, ...`parts`) => readonly \[`string` \| `null`, `string` \| `null`, `unknown`\] | Build a cache key scoped to this App's surface and its currently selected Computer, followed by the given key parts. |
+
+## Functions
+
+### useFeedQuery()
+
+```ts
+function useFeedQuery<T>(
+  queryKey,
+  watch,
+  options?,
+): UseQueryResult<FeedSnapshot<T>, AppError>;
+```
+
+Query owns sharing and teardown; Effect supplies a bounded latest-snapshot
+queue.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+#### Parameters
+
+| Parameter          | Type                                                                   |
+| ------------------ | ---------------------------------------------------------------------- |
+| `queryKey`         | readonly `unknown`[]                                                   |
+| `watch`            | [`FeedWatch`](#feedwatch)\<`T`\>                                       |
+| `options`          | \{ `enabled?`: `boolean`; `meta?`: `Record`\<`string`, `unknown`\>; \} |
+| `options.enabled?` | `boolean`                                                              |
+| `options.meta?`    | `Record`\<`string`, `unknown`\>                                        |
+
+#### Returns
+
+`UseQueryResult`\<[`FeedSnapshot`](#feedsnapshot)\<`T`\>,
+[`AppError`](errors.md#apperror)\>
+
+---
+
+### createQueryClient()
+
+```ts
+function createQueryClient(): QueryClient;
+```
+
+App defaults and grant lifetime binding, using the host's ordinary cache.
+
+#### Returns
+
+`QueryClient`
+
+---
+
+### capabilityQuery()
+
+```ts
+function capabilityQuery<H, T>(
+  app,
+  contract,
+  queryKey,
+  run,
+): OmitKeyof<UseQueryOptions<T, AppError, T, readonly unknown[]>, "queryFn"> &
+  object &
+  QueryKeyWithDataTag<readonly unknown[], T, AppError>;
+```
+
+Decode capabilities through their owner; Query owns cancellation and retries.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `H`            |
+| `T`            |
+
+#### Parameters
+
+| Parameter  | Type                                                       |
+| ---------- | ---------------------------------------------------------- |
+| `app`      | [`QueryApp`](#queryapp) \| `null`                          |
+| `contract` | [`CapabilityContract`](index.md#capabilitycontract)\<`H`\> |
+| `queryKey` | readonly `unknown`[]                                       |
+| `run`      | (`handle`, `signal`) => `Promise`\<`T`\>                   |
+
+#### Returns
+
+`OmitKeyof`\<`UseQueryOptions`\<`T`, [`AppError`](errors.md#apperror), `T`,
+readonly `unknown`[]\>, `"queryFn"`\> & `object` &
+`QueryKeyWithDataTag`\<readonly `unknown`[], `T`,
+[`AppError`](errors.md#apperror)\>
+
+---
+
+### optimisticMutation()
+
+```ts
+function optimisticMutation<TData, TVars, TResult>(
+  options,
+): WithRequired<
+  UseMutationOptions<
+    TResult,
+    AppError,
+    TVars,
+    | {
+        previous: TData;
+        optimistic: TData | undefined;
+      }
+    | undefined
+  >,
+  "mutationKey"
+>;
+```
+
+Optimistic writes for one cache entry, followed by owner reconciliation. Apply
+must return new data. Concurrent writes to this key run in order; queued writes
+wait for reconciliation instead of stacking rollback snapshots.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `TData`        | -            |
+| `TVars`        | -            |
+| `TResult`      | `unknown`    |
+
+#### Parameters
+
+| Parameter            | Type                                                                                                                                           |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`            | \{ `queryKey`: readonly `unknown`[]; `mutationFn`: `MutationFunction`\<`TResult`, `TVars`\>; `apply`: (`previous`, `variables`) => `TData`; \} |
+| `options.queryKey`   | readonly `unknown`[]                                                                                                                           |
+| `options.mutationFn` | `MutationFunction`\<`TResult`, `TVars`\>                                                                                                       |
+| `options.apply`      | (`previous`, `variables`) => `TData`                                                                                                           |
+
+#### Returns
+
+`WithRequired`\<`UseMutationOptions`\<`TResult`,
+[`AppError`](errors.md#apperror), `TVars`, \| \{ `previous`: `TData`;
+`optimistic`: `TData` \| `undefined`; \} \| `undefined`\>, `"mutationKey"`\>
+
+---
+
+### useMemberInbox()
+
+```ts
+function useMemberInbox(app): object;
+```
+
+One shared inbox watch; reloads and stream failures retain the last live rows.
+
+#### Parameters
+
+| Parameter | Type                              |
+| --------- | --------------------------------- |
+| `app`     | [`QueryApp`](#queryapp) \| `null` |
+
+#### Returns
+
+| Name        | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Default value | Description                                                                                       |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
+| `items`     | readonly ( \| \{ `agentId`: `string`; `sessionId`: `string`; `title`: `string`; `triggerId?`: `string`; `createdAt`: `number`; `lastActivityAt`: `number`; `settledAt?`: `number`; `visitedAt?`: `number`; `state`: `"running"` \| `"done"` \| `"needs_you"` \| `"errored"`; \} \| \{ `agentId`: `string`; `sessionId`: `string`; `state`: `"unavailable"`; \} \| \{ `kind`: `"workflow-review"`; `key`: \{ `runId`: `string`; `nodeId`: `string`; `iteration`: `string`; \}; `installationId`: `string`; `workflowId`: `string` \| `null`; `workflowTitle`: `string`; `reviewTitle`: `string`; `reviewers`: `"runner"` \| `"owners"`; `show`: readonly `Json`[]; `choices?`: readonly `string`[]; `openedAt`: `number`; `expiresAt`: `number`; `state`: `"pending"` \| `"closed"` \| `"answered"` \| `"delivered"` \| `"timed_out"`; \})[] | -             | -                                                                                                 |
+| `status`    | `"error"` \| `"loading"` \| `"live"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -             | -                                                                                                 |
+| `error`     | [`AppError`](errors.md#apperror) \| `null`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `query.error` | -                                                                                                 |
+| `refresh()` | () => `void`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | -             | Restart the inbox watch; use after a change that the live feed would not otherwise observe.       |
+| `visit()`   | (`agentId`, `sessionId`) => `Promise`\<`void`\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | -             | Record that the member visited one agent session, so the inbox can clear its unread state for it. |

package/docs/api/react.md

@@ -0,0 +1,216 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+[@fungi.computer/agar](modules.md) / react
+
+# react
+
+## Type Aliases
+
+### AppMountState
+
+```ts
+type AppMountState = Readonly<
+  | {
+      app: AppRoot;
+      status: "live";
+    }
+  | {
+      app: null;
+      status: "connecting" | "standalone" | "ended";
+    }
+>;
+```
+
+The App connection state passed to `mountApp`'s `render` callback: `live` once
+connected, or `connecting`/`standalone`/`ended` while there is no usable App.
+
+---
+
+### AppMountOptions
+
+```ts
+type AppMountOptions = Readonly<{
+  name: string;
+  queryClient?: QueryClient;
+}>;
+```
+
+Options passed to `mountApp`.
+
+---
+
+### HostNavigationOptions
+
+```ts
+type HostNavigationOptions = Readonly<{
+  canGoBack: boolean;
+  title?: string;
+  onBack: AppBackHandler;
+}>;
+```
+
+What an App's router can do now, and how it goes back.
+
+## Functions
+
+### mountApp()
+
+```ts
+function mountApp(element, options, render): Disposer;
+```
+
+Own this page's React root, authenticated App connection and host theme.
+
+#### Parameters
+
+| Parameter | Type                                  |
+| --------- | ------------------------------------- |
+| `element` | `HTMLElement`                         |
+| `options` | [`AppMountOptions`](#appmountoptions) |
+| `render`  | (`state`) => `ReactNode`              |
+
+#### Returns
+
+[`Disposer`](index.md#disposer)
+
+---
+
+### useStore()
+
+```ts
+function useStore<T>(store): T | undefined;
+```
+
+Read an SDK snapshot and release its subscription when the store changes.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+#### Parameters
+
+| Parameter | Type                                                            |
+| --------- | --------------------------------------------------------------- |
+| `store`   | [`ReadonlyStore`](index.md#readonlystore)\<`T`\> \| `undefined` |
+
+#### Returns
+
+`T` \| `undefined`
+
+---
+
+### useAppContext()
+
+```ts
+function useAppContext(app): AppContext | null;
+```
+
+Read the App's live context (focus, visibility, Computer selection, any pending
+open request), or null while there is no connected App.
+
+#### Parameters
+
+| Parameter | Type                                                   |
+| --------- | ------------------------------------------------------ |
+| `app`     | [`AppRoot`](index.md#approot) \| `null` \| `undefined` |
+
+#### Returns
+
+[`AppContext`](index.md#appcontext) \| `null`
+
+---
+
+### useComputerId()
+
+```ts
+function useComputerId(app): string | null;
+```
+
+Read the id of the Computer currently selected for this App, or null when no App
+is connected or no Computer is selected yet.
+
+#### Parameters
+
+| Parameter | Type                                                   |
+| --------- | ------------------------------------------------------ |
+| `app`     | [`AppRoot`](index.md#approot) \| `null` \| `undefined` |
+
+#### Returns
+
+`string` \| `null`
+
+---
+
+### useWindowStatus()
+
+```ts
+function useWindowStatus(app, items, onAction?, onReportFailure?): void;
+```
+
+Keep this window's status bar items current in the host while mounted, and hear
+the person use them. Items compare by value; the bar clears on unmount.
+
+#### Parameters
+
+| Parameter          | Type                                                                     | Description                                            |
+| ------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------ |
+| `app`              | `Pick`\<[`AppRoot`](index.md#approot), `"ui"`\> \| `null` \| `undefined` | -                                                      |
+| `items`            | readonly [`AppStatusItem`](index.md#appstatusitem)[]                     | -                                                      |
+| `onAction?`        | [`AppStatusActionHandler`](index.md#appstatusactionhandler)              | -                                                      |
+| `onReportFailure?` | (`cause`) => `void`                                                      | Hear a report the host refused, so the App can say so. |
+
+#### Returns
+
+`void`
+
+---
+
+### useAppCommandCatalog()
+
+```ts
+function useAppCommandCatalog(app, __namedParameters, build): WhistleRuntime;
+```
+
+Own one catalog's local slash runtime and host registrations. Memoize `build`
+with useCallback; changing it replaces the catalog and its availability.
+
+#### Parameters
+
+| Parameter           | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `app`               | [`AppRoot`](index.md#approot) \| `null` \| `undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `__namedParameters` | `Pick`\<`WhistleContribution`, `"sourceId"` \| `"namespace"`\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `build`             | () => readonly `Readonly`\<\{ `id`: `string`; `title`: `string`; `category`: `string`; `description?`: `string`; `projections?`: \{ `bindings?`: \{ `order?`: `number`; `values`: readonly `string`[]; \}; `agent?`: \{ `keybind?`: `string`; `order?`: `number`; \}; `help?`: \{ `order?`: `number`; \}; `menu?`: \{ `order?`: `number`; \}; `palette?`: \{ `order?`: `number`; \}; `slash?`: \{ `aliases`: readonly `string`[]; `order?`: `number`; `arguments?`: \{ `hint`: `string`; `words?`: ... \| ...; `text?`: ... \| ...; \}; \}; \}; `action?`: \{ `inputSchema?`: \{ \[`key`: `string`\]: \| `string` \| `number` \| `boolean` \| readonly string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| ... 4 more ... \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| ...[] \| \{ \[`key`: `string`\]: string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| ... 4 more ... \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| ...; \} \| `null`; \}; `outputSchema?`: \{ \[`key`: `string`\]: \| `string` \| `number` \| `boolean` \| readonly string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| ... 4 more ... \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| ...[] \| \{ \[`key`: `string`\]: string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| number \| boolean \| readonly (string \| ... 4 more ... \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \| ...; \} \| `null`; \}; `presentation?`: \| \{ `type`: `"action"`; \} \| \{ `type`: `"custom"`; `data`: \{ \[`key`: `string`\]: \| `string` \| `number` \| `boolean` \| readonly ...[] \| \{ \[`key`: ...\]: ...; \} \| `null`; \}; \} \| \{ `type`: `"choice"`; `options`: readonly `object`[]; \} \| \{ `type`: `"form"`; `submitLabel?`: `string`; \} \| \{ `type`: `"confirmation"`; `message`: `string`; `confirmLabel?`: `string`; `cancelLabel?`: `string`; \}; \}; `availability?`: () => `WhistleAvailability`; `handler`: (`input`) => `unknown`; \}\>[] |
+
+#### Returns
+
+`WhistleRuntime`
+
+---
+
+### useHostNavigation()
+
+```ts
+function useHostNavigation(navigation, __namedParameters): void;
+```
+
+Publish an App's navigation state to its host and own the host's Back requests
+while mounted. Pass `app?.window.navigation`; with no connected App it does
+nothing. Unmounting withdraws Back from the host chrome.
+
+#### Parameters
+
+| Parameter           | Type                                                                                                                       |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `navigation`        | \| `Readonly`\<\{ `publish`: `Promise`\<`void`\>; `onBack`: [`Disposer`](index.md#disposer); \}\> \| `null` \| `undefined` |
+| `__namedParameters` | [`HostNavigationOptions`](#hostnavigationoptions)                                                                          |
+
+#### Returns
+
+`void`