@fungi.computer/agar 0.0.0-stage → 0.0.1

package/docs/api/media-json.md

@@ -0,0 +1,507 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+[@fungi.computer/agar](modules.md) / media-json
+
+# media-json
+
+## Classes
+
+### MediaGeneration
+
+Page-side Agar handle over an admitted generic JSON method caller.
+
+#### Extends
+
+- `RpcTarget`
+
+#### Implements
+
+- [`MediaGenerationHandle`](index.md#mediagenerationhandle)
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new MediaGeneration(
+   call,
+   computerId,
+   signal?
+): MediaGeneration;
+```
+
+###### Parameters
+
+| Parameter    | Type                                                      |
+| ------------ | --------------------------------------------------------- |
+| `call`       | [`MediaGenerationJsonCaller`](#mediagenerationjsoncaller) |
+| `computerId` | `string`                                                  |
+| `signal?`    | `AbortSignal`                                             |
+
+###### Returns
+
+[`MediaGeneration`](#mediageneration)
+
+###### Overrides
+
+```ts
+RpcTarget.constructor;
+```
+
+#### Methods
+
+##### describe()
+
+```ts
+describe(): Promise<Readonly<{
+  computerId: string;
+  canGenerate: boolean;
+  models: readonly object[];
+}>>;
+```
+
+Describe this handle's fixed Computer through the admitted JSON method.
+
+###### Returns
+
+`Promise`\<`Readonly`\<\{ `computerId`: `string`; `canGenerate`: `boolean`;
+`models`: readonly `object`[]; \}\>\>
+
+###### Implementation of
+
+```ts
+MediaGenerationHandle.describe;
+```
+
+##### createAttempt()
+
+```ts
+createAttempt(): Promise<MediaGenerationAttempt>;
+```
+
+Issue a canonical replay identity for a new generation attempt.
+
+###### Returns
+
+`Promise`\<[`MediaGenerationAttempt`](#mediagenerationattempt)\>
+
+###### Implementation of
+
+```ts
+MediaGenerationHandle.createAttempt;
+```
+
+##### restoreAttempt()
+
+```ts
+restoreAttempt(reference): Promise<MediaGenerationAttempt>;
+```
+
+Resume the original Computer and canonical request without issuing a new ID.
+
+###### Parameters
+
+| Parameter              | Type                                                 |
+| ---------------------- | ---------------------------------------------------- |
+| `reference`            | \{ `requestId`: `string`; `computerId`: `string`; \} |
+| `reference.requestId`  | `string`                                             |
+| `reference.computerId` | `string`                                             |
+
+###### Returns
+
+`Promise`\<[`MediaGenerationAttempt`](#mediagenerationattempt)\>
+
+###### Implementation of
+
+```ts
+MediaGenerationHandle.restoreAttempt;
+```
+
+##### cancelAttempt()
+
+```ts
+cancelAttempt(reference): Promise<void>;
+```
+
+Abort every active browser request belonging to this attempt.
+
+###### Parameters
+
+| Parameter              | Type                                                 |
+| ---------------------- | ---------------------------------------------------- |
+| `reference`            | \{ `requestId`: `string`; `computerId`: `string`; \} |
+| `reference.requestId`  | `string`                                             |
+| `reference.computerId` | `string`                                             |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+###### Implementation of
+
+```ts
+MediaGenerationHandle.cancelAttempt;
+```
+
+---
+
+### MediaGenerationAttempt
+
+One replayable host-issued Media attempt, sharing cancellation with its handle.
+
+#### Extends
+
+- `RpcTarget`
+
+#### Implements
+
+- [`MediaGenerationAttemptHandle`](index.md#mediagenerationattempthandle)
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new MediaGenerationAttempt(
+   call,
+   computerId,
+   signal,
+   requestId,
+   activeRequests
+): MediaGenerationAttempt;
+```
+
+###### Parameters
+
+| Parameter        | Type                                                      |
+| ---------------- | --------------------------------------------------------- |
+| `call`           | [`MediaGenerationJsonCaller`](#mediagenerationjsoncaller) |
+| `computerId`     | `string`                                                  |
+| `signal`         | `AbortSignal` \| `undefined`                              |
+| `requestId`      | `string`                                                  |
+| `activeRequests` | `Map`\<`string`, `Set`\<`AbortController`\>\>             |
+
+###### Returns
+
+[`MediaGenerationAttempt`](#mediagenerationattempt)
+
+###### Overrides
+
+```ts
+RpcTarget.constructor;
+```
+
+#### Methods
+
+##### reference()
+
+```ts
+reference(): Promise<{
+  requestId: string;
+  computerId: string;
+}>;
+```
+
+Return the stable Computer and request identity for replay.
+
+###### Returns
+
+`Promise`\<\{ `requestId`: `string`; `computerId`: `string`; \}\>
+
+###### Implementation of
+
+```ts
+MediaGenerationAttemptHandle.reference;
+```
+
+##### generate()
+
+```ts
+generate(input): Promise<MediaGenerationOutcome>;
+```
+
+Save through the admitted host; poll pending work with the same replay identity.
+
+###### Parameters
+
+| Parameter | Type                                                    |
+| --------- | ------------------------------------------------------- |
+| `input`   | [`MediaGenerationInput`](index.md#mediagenerationinput) |
+
+###### Returns
+
+`Promise`\<[`MediaGenerationOutcome`](index.md#mediagenerationoutcome)\>
+
+###### Implementation of
+
+```ts
+MediaGenerationAttemptHandle.generate;
+```
+
+## Type Aliases
+
+### MediaGenerationJsonCaller
+
+```ts
+type MediaGenerationJsonCaller = (
+  method,
+  input?,
+  options?,
+) => Promise<Schema.Json | undefined>;
+```
+
+Page-local generic JSON method caller. Signals never enter JSON or RPC.
+
+#### Parameters
+
+| Parameter         | Type                            |
+| ----------------- | ------------------------------- |
+| `method`          | `string`                        |
+| `input?`          | `Schema.Json`                   |
+| `options?`        | \{ `signal?`: `AbortSignal`; \} |
+| `options.signal?` | `AbortSignal`                   |
+
+#### Returns
+
+`Promise`\<`Schema.Json` \| `undefined`\>
+
+---
+
+### MediaGenerationJsonRequest
+
+```ts
+type MediaGenerationJsonRequest = Schema.Schema.Type<
+  typeof mediaGenerationJsonRequestSchema
+>;
+```
+
+Plain JSON generation input for an admitted capability's generate method.
+
+---
+
+### MediaGenerationJsonReply
+
+```ts
+type MediaGenerationJsonReply = Schema.Schema.Type<
+  typeof mediaGenerationJsonReplySchema
+>;
+```
+
+JSON generation reply, including the shared Pending owner.
+
+---
+
+### MediaGenerationDescription
+
+```ts
+type MediaGenerationDescription = Readonly<{
+  computerId: string;
+  canGenerate: boolean;
+  models: readonly MediaModel[];
+}>;
+```
+
+Catalog and permission snapshot for the handle's fixed Computer.
+
+## Variables
+
+### mediaGenerationDescriptionSchema
+
+```ts
+const mediaGenerationDescriptionSchema: Struct<{
+  computerId: String;
+  canGenerate: Boolean;
+  models: $Array<Struct<{
+     id: String;
+     input: Struct<{
+        defaultHeight: Number;
+        defaultSteps: NullOr<Number>;
+        defaultWidth: Number;
+        dimensions: Literals<readonly ["none", "own"]>;
+        maxDimension: NullOr<Number>;
+        maxReferences: Number;
+        maxSteps: NullOr<Number>;
+        referenceField: NullOr<String>;
+        steps: Literals<readonly ["steps", "num_steps", "fixed"]>;
+        transport: Literals<readonly ["json", "multipart"]>;
+     }>;
+     kind: Literals<readonly ["image", "video"]>;
+     label: String;
+     tier: Literals<readonly ["draft", "balanced", "premium", "max"]>;
+     outputFormats: $Array<Literals<readonly ["png", "jpeg", "webp"]>>;
+     sizes: NullOr<$Array<String>>;
+     video: NullOr<Struct<{
+        minSeconds: Number;
+        maxSeconds: Number;
+        defaultSeconds: Number;
+        durations: $Array<Number>;
+        provider: Literals<readonly ["seedance", "veo", "minimax"]>;
+        formats: $Array<Struct<{
+           resolution: ...;
+           aspectRatio: ...;
+           width: ...;
+           height: ...;
+        }>>;
+        defaultResolution: Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>;
+        defaultAspectRatio: Literals<readonly ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"]>;
+        defaultGenerateAudio: NullOr<Boolean>;
+        maxPromptLength: Number;
+        referenceRoles: $Array<Literals<readonly [..., ..., ...]>>;
+        maxReferenceImages: Number;
+        referenceResolutions: $Array<Literals<readonly [..., ..., ..., ..., ...]>>;
+        prices: $Array<Struct<{
+           resolution: ...;
+           silentMilliunitsPerSecond: ...;
+           audioMilliunitsPerSecond: ...;
+        }>>;
+     }>>;
+  }>>;
+}>;
+```
+
+Plain JSON catalog reply, decoded with Agar's Media model grammar.
+
+---
+
+### mediaGenerationJsonRequestSchema
+
+```ts
+const mediaGenerationJsonRequestSchema: Struct<{
+  requestId: String;
+  settings: Struct<{
+     model: String;
+     prompt: String;
+     width: Number;
+     height: Number;
+     steps: optional<Number>;
+     durationSeconds: optional<Number>;
+     resolution: optional<Literals<readonly ["480p", "720p", "768p", "1080p", "4k"]>>;
+     aspectRatio: optional<Literals<readonly ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"]>>;
+     generateAudio: optional<Boolean>;
+     references: optional<$Array<Struct<{
+        path: String;
+        role: optional<Literals<readonly [..., ..., ...]>>;
+     }>>>;
+  }>;
+  destination: Struct<{
+     path: String;
+  }>;
+}>;
+```
+
+A generation call carries paths and a replay ID; the host supplies authority.
+
+---
+
+### mediaGenerationJsonOutcomeSchema
+
+```ts
+const mediaGenerationJsonOutcomeSchema: Union<
+  readonly [
+    Struct<{
+      kind: Literal<"succeeded">;
+      result: Struct<{
+        [dispose]: optional<Unknown>;
+        bytes: Number;
+        costMilliunits: Number;
+        destination: Struct<{
+          computerId: String;
+          path: String;
+        }>;
+        format: Literals<readonly ["png", "jpeg", "gif", "webp", "mp4"]>;
+        height: Number;
+        model: String;
+        width: Number;
+      }>;
+    }>,
+    Struct<{
+      kind: Literal<"failed">;
+      failure: Struct<{
+        message: String;
+        stage: optional<
+          Literals<
+            readonly [
+              "admission",
+              "generation-authorization",
+              "settings",
+              "estimate",
+              "billing",
+              "operation",
+              "provider",
+              "normalization",
+              "artifact",
+              "destination-authorization",
+              "destination-write",
+            ]
+          >
+        >;
+        code: Literals<
+          readonly [
+            "CANCELLED",
+            "CAPABILITY_DENIED",
+            "CAPABILITY_REVOKED",
+            "DISCONNECTED",
+            "HOST_FAILURE",
+            "IDENTITY",
+            "INSUFFICIENT_CREDIT",
+            "INVALID_ARGUMENT",
+            "PROTOCOL",
+            "SAFETY_FILTER_REFUSED",
+            "TIMEOUT",
+          ]
+        >;
+        retryable: Boolean;
+      }>;
+    }>,
+  ]
+>;
+```
+
+A typed completion or refusal; no live attempt handles cross this boundary.
+
+---
+
+### mediaGenerationJsonReplySchema
+
+```ts
+const mediaGenerationJsonReplySchema: Union<readonly [Union<readonly [Struct<{
+  kind: Literal<"succeeded">;
+  result: Struct<{
+     [dispose]: optional<Unknown>;
+     bytes: Number;
+     costMilliunits: Number;
+     destination: Struct<{
+        computerId: String;
+        path: String;
+     }>;
+     format: Literals<readonly ["png", "jpeg", "gif", "webp", "mp4"]>;
+     height: Number;
+     model: String;
+     width: Number;
+  }>;
+}>, Struct<{
+  kind: Literal<"failed">;
+  failure: Struct<{
+     message: String;
+     stage: optional<Literals<readonly [..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ...]>>;
+     code: Literals<readonly ["CANCELLED", "CAPABILITY_DENIED", "CAPABILITY_REVOKED", "DISCONNECTED", "HOST_FAILURE", "IDENTITY", "INSUFFICIENT_CREDIT", "INVALID_ARGUMENT", "PROTOCOL", "SAFETY_FILTER_REFUSED", "TIMEOUT"]>;
+     retryable: Boolean;
+  }>;
+}>]>, declare<Readonly<{
+  kind: "pending";
+  retryAfterMs: number;
+}>, unknown>]>;
+```
+
+Generate may also report Agar's canonical, bounded Pending result.
+
+## References
+
+### mediaGenerationReferenceSchema
+
+Re-exports
+[mediaGenerationReferenceSchema](index.md#mediagenerationreferenceschema)

package/docs/api/media-request-id.md

@@ -0,0 +1,32 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+[@fungi.computer/agar](modules.md) / media-request-id
+
+# media-request-id
+
+## Variables
+
+### mediaRequestIds
+
+```ts
+const mediaRequestIds: Readonly<{
+  request: IdCodec<"hub-media-request", "request", 1>;
+}>;
+```
+
+One canonical identity for a retryable Media operation.
+
+---
+
+### mediaRequestIdSchema
+
+```ts
+const mediaRequestIdSchema: ZodString;
+```
+
+Public wire grammar for the canonical retry identity, visible in App JSON
+schemas.

package/docs/api/modules.md

@@ -0,0 +1,32 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+# @fungi.computer/agar
+
+## Modules
+
+| Module                                        | Description |
+| --------------------------------------------- | ----------- |
+| [app-build-contract](app-build-contract.md)   | -           |
+| [backend-declaration](backend-declaration.md) | -           |
+| [backend-definition](backend-definition.md)   | -           |
+| [backend](backend.md)                         | -           |
+| [errors](errors.md)                           | -           |
+| [files](files.md)                             | -           |
+| [gills](gills.md)                             | -           |
+| [git-commit](git-commit.md)                   | -           |
+| [git-rpc](git-rpc.md)                         | -           |
+| [git-steps](git-steps.md)                     | -           |
+| [git-wire](git-wire.md)                       | -           |
+| [git](git.md)                                 | -           |
+| [index](index.md)                             | -           |
+| [media-json](media-json.md)                   | -           |
+| [media-request-id](media-request-id.md)       | -           |
+| [query](query.md)                             | -           |
+| [react](react.md)                             | -           |
+| [read-copy](read-copy.md)                     | -           |
+| [rpc](rpc.md)                                 | -           |
+| [storage](storage.md)                         | -           |