gills

Import

Import

import * as api from "@fungi.computer/gills";

Exports

Kind	Export	Description
Ttype alias	AppGillDesktopSize	Sizes the App explicitly offers for a desktop Gill.
Ttype alias	AppGillParam	One App-owned placement selector.
Ttype alias	AppGillWatch	An existing change feed used to refresh a Gill.
Ttype alias	AppDeclaredGill	A digest-covered projection of one declared read method.
Ttype alias	GillRequest	Selectors supplied by a Gill caller.
Ttype alias	GillCall	Input to the generated backend Gill entry.
Ttype alias	GillResponse	A decoded page of plain-text Gill rows or a bounded error.
Ttype alias	GillOptionsResponse	Choices remain within the selected App; the host supplies Computer choices.
Ttype alias	GillReply	A rows read or a placement-options read.
Ttype alias	RowV1	One shared, bounded data row; the host owns navigation and execution.
constconstant	appGillParamKeySchema	Bounded, App-owned parameter key.
constconstant	appGillParamSchema	Placement parameter metadata, included in the Release digest.
constconstant	appGillParamsSchema	The bounded, uniquely keyed placement parameters shared with desktop catalogs.
constconstant	appGillWatchSchema	A storage marker or host binding’s existing change feed.
constconstant	appDeclaredGillSchema	Digest-covered identity, source, context and desktop sizes of a Gill.
constconstant	gillParamsSchema	Placement values are bounded; the admitting host checks declared keys.
constconstant	gillRequestSchema	The caller supplies placement context and a source-owned continuation.
constconstant	gillCallSchema	Runtime call selected by the host after admitting a declared source.
constconstant	gillResponseSchema	Shared response codec. Rows are plain text and cannot carry executable UI.
constconstant	decodeGillResponse	Decode backend output once at the App host boundary.
constconstant	gillOptionsResponseSchema	A bounded choice page returned by an App-owned options read method.
constconstant	gillReplySchema	Shared wire for a rows read or a placement-options read.
constconstant	decodeGillReply	Decode the selected host’s bounded reply before rendering or navigation.
constconstant	decodeGillOptionsResponse	Decode an options method’s result without trusting extra fields.
constconstant	rowLabelSchemaV1	Nonempty display text, bounded to 4,096 characters.
constconstant	rowIdentitySchemaV1	Producer-owned row identity, bounded to 513 characters.
constconstant	rowOpenSchemaV1	A navigation parameter interpreted only by the receiving App.
constconstant	rowSchemaV1	A bounded text row; each receiving host authorizes its open target.
constconstant	rowPageSchemaV1	A page containing at most 200 shared rows.
fnfunction	decodeDeclaredGillResponse()	App output must match its digest-covered view identity.
fnfunction	createGillClient()	Authenticated host Fetch stays outside App code and is pinned to one selection.

AppGillDesktopSizeTtype alias

Signature

type AppGillDesktopSize = "S" | "M" | "L";

Sizes the App explicitly offers for a desktop Gill.

---

AppGillParamTtype alias

Signature

type AppGillParam = Readonly<{
  key: string;
  label: string;
  kind: "computer" | "repository" | "branch";
  required: boolean;
  options?: string;
}>;

One App-owned placement selector.

---

AppGillWatchTtype alias

Signature

type AppGillWatch = Readonly<
  | {
      storage: string;
    }
  | {
      binding: string;
    }
>;

An existing change feed used to refresh a Gill.

---

AppDeclaredGillTtype alias

Signature

type AppDeclaredGill = Readonly<{
  id: string;
  source: string;
  title: string;
  params?: readonly AppGillParam[];
  watch?: AppGillWatch;
  desktop?: Readonly<{
    sizes: readonly AppGillDesktopSize[];
  }>;
}>;

A digest-covered projection of one declared read method.

---

GillRequestTtype alias

Signature

type GillRequest = Schema.Schema.Type<typeof gillRequestSchema>;

Selectors supplied by a Gill caller.

---

GillCallTtype alias

Signature

type GillCall = Schema.Schema.Type<typeof gillCallSchema>;

Input to the generated backend Gill entry.

---

GillResponseTtype alias

Signature

type GillResponse = Schema.Schema.Type<typeof gillResponseSchema>;

A decoded page of plain-text Gill rows or a bounded error.

---

GillOptionsResponseTtype alias

Signature

type GillOptionsResponse = Schema.Schema.Type<typeof gillOptionsResponseSchema>;

Choices remain within the selected App; the host supplies Computer choices.

---

GillReplyTtype alias

Signature

type GillReply = Schema.Schema.Type<typeof gillReplySchema>;

A rows read or a placement-options read.

---

RowV1Ttype alias

Signature

type RowV1 = Schema.Schema.Type<typeof rowSchemaV1>;

One shared, bounded data row; the host owns navigation and execution.

appGillParamKeySchemaconstconstant

Signature

const appGillParamKeySchema: String;

Bounded, App-owned parameter key.

---

appGillParamSchemaconstconstant

Signature

const appGillParamSchema: Struct<{
  key: String;
  label: String;
  kind: Literals<readonly ["computer", "repository", "branch"]>;
  required: Boolean;
  options: optional<String>;
}>;

Placement parameter metadata, included in the Release digest.

---

appGillParamsSchemaconstconstant

Signature

const appGillParamsSchema: $Array<
  Struct<{
    key: String;
    label: String;
    kind: Literals<readonly ["computer", "repository", "branch"]>;
    required: Boolean;
    options: optional<String>;
  }>
>;

The bounded, uniquely keyed placement parameters shared with desktop catalogs.

---

appGillWatchSchemaconstconstant

Signature

const appGillWatchSchema: Union<
  readonly [
    Struct<{
      storage: String;
    }>,
    Struct<{
      binding: String;
    }>,
  ]
>;

A storage marker or host binding’s existing change feed.

---

appDeclaredGillSchemaconstconstant

Signature

const appDeclaredGillSchema: Schema.Codec<AppDeclaredGill>;

Digest-covered identity, source, context and desktop sizes of a Gill.

---

gillParamsSchemaconstconstant

Signature

const gillParamsSchema: $Record<String, String>;

Placement values are bounded; the admitting host checks declared keys.

---

gillRequestSchemaconstconstant

Signature

const gillRequestSchema: Struct<{
  viewId: String;
  params: optional<$Record<String, String>>;
  after: optional<String>;
  options: optional<String>;
}>;

The caller supplies placement context and a source-owned continuation.

---

gillCallSchemaconstconstant

Signature

const gillCallSchema: Struct<{
  id: String;
  params: optional<$Record<String, String>>;
  after: optional<String>;
  options: optional<String>;
}>;

Runtime call selected by the host after admitting a declared source.

---

gillResponseSchemaconstconstant

Signature

const gillResponseSchema: Union<readonly [Struct<{
  viewId: String;
  title: String;
  state: Literal<"empty">;
  rows: Tuple<readonly []>;
  next: optional<String>;
}>, Struct<{
  viewId: String;
  title: String;
  state: Literal<"error">;
  rows: Tuple<readonly []>;
  reason: optional<Literals<readonly ["exec_isolation_required", "params_required"]>>;
  error: String;
  recovery: optional<Union<readonly [Struct<{
     kind: Literal<"configure">;
     param: String;
   }>, Struct<{
     kind: Literal<"open">;
  }>]>>;
}>, Struct<{
  viewId: String;
  title: String;
  state: Literal<"full">;
  rows: $Array<Struct<{
     id: String;
     title: String;
     detail: optional<String>;
     tone: optional<Literals<readonly ["attention", "running", "error", "settled", "muted"]>>;
     status: optional<Struct<{
        label: String;
        tone: Literals<...>;
     }>>;
     open: optional<Struct<{
        params: $Array<...>;
     }>>;
  }>>;
  next: optional<String>;
}>]>;

Shared response codec. Rows are plain text and cannot carry executable UI.

---

decodeGillResponseconstconstant

Signature

const decodeGillResponse: (
  input,
  options?,
) =>
  | {
      viewId: string;
      title: string;
      state: "empty";
      rows: readonly [];
      next?: string;
    }
  | {
      viewId: string;
      title: string;
      state: "error";
      rows: readonly [];
      reason?: "exec_isolation_required" | "params_required";
      error: string;
      recovery?:
        | {
            kind: "configure";
            param: string;
          }
        | {
            kind: "open";
          };
    }
  | {
      viewId: string;
      title: string;
      state: "full";
      rows: readonly object[];
      next?: string;
    };

Decode backend output once at the App host boundary.

Parameters

Parameter	Type
input	unknown
options?	ParseOptions

Returns

Type Literal

Signature

{
  viewId: string;
  title: string;
  state: "empty";
  rows: readonly [];
  next?: string;
}

---

Type Literal

Signature

{
  viewId: string;
  title: string;
  state: "error";
  rows: readonly [];
  reason?: "exec_isolation_required" | "params_required";
  error: string;
  recovery?:   | {
     kind: "configure";
     param: string;
   }
     | {
     kind: "open";
   };
}

Name	Type	Default value	Description
viewId	string	identity	-
title	string	label	-
state	"error"	-	-
rows	readonly []	-	-
reason?	"exec_isolation_required" | "params_required"	-	Host-owned permanent execution refusal; an ordinary error may still be refreshed.
error	string	-	-
recovery?	| { kind: "configure"; param: string; } | { kind: "open"; }	-	The host supplies the same-placement picker and this App’s launch.

---

Type Literal

Signature

{
  viewId: string;
  title: string;
  state: "full";
  rows: readonly object[];
  next?: string;
}

---

gillOptionsResponseSchemaconstconstant

Signature

const gillOptionsResponseSchema: Struct<{
  options: $Array<
    Struct<{
      value: String;
      label: String;
      detail: optional<String>;
    }>
  >;
  next: optional<String>;
}>;

A bounded choice page returned by an App-owned options read method.

---

gillReplySchemaconstconstant

Signature

const gillReplySchema: Union<readonly [Union<readonly [Struct<{
  viewId: String;
  title: String;
  state: Literal<"empty">;
  rows: Tuple<readonly []>;
  next: optional<String>;
}>, Struct<{
  viewId: String;
  title: String;
  state: Literal<"error">;
  rows: Tuple<readonly []>;
  reason: optional<Literals<readonly ["exec_isolation_required", "params_required"]>>;
  error: String;
  recovery: optional<Union<readonly [Struct<{
     kind: ...;
     param: ...;
   }>, Struct<{
     kind: ...;
  }>]>>;
}>, Struct<{
  viewId: String;
  title: String;
  state: Literal<"full">;
  rows: $Array<Struct<{
     id: String;
     title: String;
     detail: optional<String>;
     tone: optional<Literals<...>>;
     status: optional<Struct<...>>;
     open: optional<Struct<...>>;
  }>>;
  next: optional<String>;
}>]>, Struct<{
  options: $Array<Struct<{
     value: String;
     label: String;
     detail: optional<String>;
  }>>;
  next: optional<String>;
}>]>;

Shared wire for a rows read or a placement-options read.

---

decodeGillReplyconstconstant

Signature

const decodeGillReply: (
  input,
  options?,
) =>
  | {
      viewId: string;
      title: string;
      state: "empty";
      rows: readonly [];
      next?: string;
    }
  | {
      viewId: string;
      title: string;
      state: "error";
      rows: readonly [];
      reason?: "exec_isolation_required" | "params_required";
      error: string;
      recovery?:
        | {
            kind: "configure";
            param: string;
          }
        | {
            kind: "open";
          };
    }
  | {
      viewId: string;
      title: string;
      state: "full";
      rows: readonly object[];
      next?: string;
    }
  | {
      options: readonly object[];
      next?: string;
    };

Decode the selected host’s bounded reply before rendering or navigation.

Parameters

Parameter	Type
input	unknown
options?	ParseOptions

Returns

Type Literal

Signature

{
  viewId: string;
  title: string;
  state: "empty";
  rows: readonly [];
  next?: string;
}

---

Type Literal

Signature

{
  viewId: string;
  title: string;
  state: "error";
  rows: readonly [];
  reason?: "exec_isolation_required" | "params_required";
  error: string;
  recovery?:   | {
     kind: "configure";
     param: string;
   }
     | {
     kind: "open";
   };
}

Name	Type	Default value	Description
viewId	string	identity	-
title	string	label	-
state	"error"	-	-
rows	readonly []	-	-
reason?	"exec_isolation_required" | "params_required"	-	Host-owned permanent execution refusal; an ordinary error may still be refreshed.
error	string	-	-
recovery?	| { kind: "configure"; param: string; } | { kind: "open"; }	-	The host supplies the same-placement picker and this App’s launch.

---

Type Literal

Signature

{
  viewId: string;
  title: string;
  state: "full";
  rows: readonly object[];
  next?: string;
}

---

Type Literal

Signature

{
  options: readonly object[];
  next?: string;
}

---

decodeGillOptionsResponseconstconstant

Signature

const decodeGillOptionsResponse: (input, options?) => object;

Decode an options method’s result without trusting extra fields.

Parameters

Parameter	Type
input	unknown
options?	ParseOptions

Returns

object

Name	Type
options	readonly object[]
next?	string

---

rowLabelSchemaV1constconstant

Signature

const rowLabelSchemaV1: String;

Nonempty display text, bounded to 4,096 characters.

---

rowIdentitySchemaV1constconstant

Signature

const rowIdentitySchemaV1: String;

Producer-owned row identity, bounded to 513 characters.

---

rowOpenSchemaV1constconstant

Signature

const rowOpenSchemaV1: Struct<{
  params: $Array<
    Struct<{
      key: String;
      value: String;
    }>
  >;
}>;

A navigation parameter interpreted only by the receiving App.

---

rowSchemaV1constconstant

Signature

const rowSchemaV1: Struct<{
  id: String;
  title: String;
  detail: optional<String>;
  tone: optional<
    Literals<readonly ["attention", "running", "error", "settled", "muted"]>
  >;
  status: optional<
    Struct<{
      label: String;
      tone: Literals<
        readonly [
          "neutral",
          "primary",
          "secondary",
          "accent",
          "success",
          "info",
          "warning",
          "error",
        ]
      >;
    }>
  >;
  open: optional<
    Struct<{
      params: $Array<
        Struct<{
          key: String;
          value: String;
        }>
      >;
    }>
  >;
}>;

A bounded text row; each receiving host authorizes its open target.

---

rowPageSchemaV1constconstant

Signature

const rowPageSchemaV1: $Array<
  Struct<{
    id: String;
    title: String;
    detail: optional<String>;
    tone: optional<
      Literals<readonly ["attention", "running", "error", "settled", "muted"]>
    >;
    status: optional<
      Struct<{
        label: String;
        tone: Literals<
          readonly [
            "neutral",
            "primary",
            "secondary",
            "accent",
            "success",
            "info",
            "warning",
            "error",
          ]
        >;
      }>
    >;
    open: optional<
      Struct<{
        params: $Array<
          Struct<{
            key: String;
            value: String;
          }>
        >;
      }>
    >;
  }>
>;

A page containing at most 200 shared rows.

decodeDeclaredGillResponse()fnfunction

Signature

function decodeDeclaredGillResponse(
  response,
  declaration,
):
  | {
      viewId: string;
      title: string;
      state: "empty";
      rows: readonly [];
      next?: string;
    }
  | {
      viewId: string;
      title: string;
      state: "error";
      rows: readonly [];
      reason?: "exec_isolation_required" | "params_required";
      error: string;
      recovery?:
        | {
            kind: "configure";
            param: string;
          }
        | {
            kind: "open";
          };
    }
  | {
      viewId: string;
      title: string;
      state: "full";
      rows: readonly object[];
      next?: string;
    };

App output must match its digest-covered view identity.

Parameters

Parameter	Type
response	| { viewId: string; title: string; state: "empty"; rows: readonly []; next?: string; } | { viewId: string; title: string; state: "error"; rows: readonly []; reason?: "exec_isolation_required" | "params_required"; error: string; recovery?: | { kind: "configure"; param: string; } | { kind: "open"; }; } | { viewId: string; title: string; state: "full"; rows: readonly object[]; next?: string; }
declaration	Pick<AppDeclaredGill, "id" | "params">

Returns

Type Literal

Signature

{
  viewId: string;
  title: string;
  state: "empty";
  rows: readonly [];
  next?: string;
}

---

Type Literal

Signature

{
  viewId: string;
  title: string;
  state: "error";
  rows: readonly [];
  reason?: "exec_isolation_required" | "params_required";
  error: string;
  recovery?:   | {
     kind: "configure";
     param: string;
   }
     | {
     kind: "open";
   };
}

Name	Type	Default value	Description
viewId	string	identity	-
title	string	label	-
state	"error"	-	-
rows	readonly []	-	-
reason?	"exec_isolation_required" | "params_required"	-	Host-owned permanent execution refusal; an ordinary error may still be refreshed.
error	string	-	-
recovery?	| { kind: "configure"; param: string; } | { kind: "open"; }	-	The host supplies the same-placement picker and this App’s launch.

---

Type Literal

Signature

{
  viewId: string;
  title: string;
  state: "full";
  rows: readonly object[];
  next?: string;
}

---

createGillClient()fnfunction

Signature

function createGillClient(options): object;

Authenticated host Fetch stays outside App code and is pinned to one selection.

Parameters

Parameter	Type
options	Readonly<{ decodeRefusal?: (raw, declaration) => GillResponse | undefined; endpoint: string; fetch: typeof globalThis.fetch; declaration: Pick<AppDeclaredGill, "id" | "title" | "params">; }>

Returns

Name	Type	Description
request()	(selectors, signal?) => Promise< | { viewId: string; title: string; state: "empty"; rows: readonly []; next?: string; } | { viewId: string; title: string; state: "error"; rows: readonly []; reason?: "exec_isolation_required" | "params_required"; error: string; recovery?: | { kind: "configure"; param: string; } | { kind: "open"; }; } | { viewId: string; title: string; state: "full"; rows: readonly object[]; next?: string; } | { options: readonly object[]; next?: string; }>	Fetch one decoded page using this client’s pinned declaration.