@fungi.computer/gills 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+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.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# Gills (`@fungi.computer/gills`)
 
-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.
+Gills defines compact, plain-text App views shared by browser and terminal
+hosts. It owns the row wire format, Gill declarations, bounded requests and
+responses, and an authenticated-fetch client. Your host owns admission,
+navigation and read-method admission.
+
+## Install or set up
+
+```sh
+npm install @fungi.computer/gills effect@4.0.2
+```
+
+Gills is ESM. Effect is its only runtime dependency. All exports are available
+from `@fungi.computer/gills` in Node, browsers and Workers.
+
+## Quick start
+
+Decode a row page and the selectors a caller may send:
+
+```ts
+import * as Schema from "effect/Schema";
+import { rowPageSchemaV1, gillRequestSchema } from "@fungi.computer/gills";
+
+const rows = Schema.decodeUnknownSync(rowPageSchemaV1)([
+  { id: "session-a", title: "Review the draft", tone: "attention" },
+]);
+const request = Schema.decodeUnknownSync(gillRequestSchema, {
+  onExcessProperty: "error",
+})({ viewId: "inbox" });
+console.log(rows[0]?.title, request.viewId);
+```
+
+## Core concepts
+
+- A **declaration** records the Gill's App-local identity, source read method,
+  optional placement parameters and their options read methods, change feed and
+  desktop sizes. Agar generates it from the backend; Puffball includes it in the
+  Release digest.
+- A **request** contains a view ID, placement parameters and optional source
+  cursor. The host admits the method and Computer before invoking the App.
+- A **response** is an empty page, a full page of text rows, or an error. A
+  request with `options: <parameter key>` returns a choice page instead.
+  `decodeDeclaredGillResponse` rejects another view's identity.
+- A **row** carries display text and optional navigation parameters. The host
+  opens the Gill's own App; that App interprets the parameters. Rows cannot name
+  a different App, a URL, or a Session-specific target. Navigation values retain
+  up to 4,096 characters, including a Computer file path; display shortening
+  never changes navigation values.
+- Optional `row.status` carries the App's plain label and semantic tone for a
+  compact status indicator. The App maps its state; the host does not infer it.
+- An error can offer `recovery: { kind: "configure", param: "computer" }` or
+  `recovery: { kind: "open" }`. Configure must name a declared parameter and
+  opens that placement's existing picker. Open uses the host's launcher for the
+  same App. Neither form contains an App ID, URL or command. App names and icons
+  remain host directory presentation, outside this wire.
+
+## API reference
+
+See the [generated API](docs/api/index.md) for the schemas, inferred types and
+`createGillClient`.
+
+## Examples
+
+`createGillClient({ endpoint, fetch, declaration })` sends bounded selectors
+with PUT and decodes the result. Supply an authenticated `fetch` pinned to the
+selected App and Release. An optional `decodeRefusal(raw, declaration)` handles
+recognized HTTP 503 bodies using the host's own decoder. Unrecognized refusals
+throw; the client does not choose host policy.
+
+Agar's App execution refusal decoder remains in `@fungi.computer/agar/gills`.
+App producers and renderers import the shared contract directly from this
+package.
+
+## Limits and errors
+
+Pages contain at most 200 rows. Row labels allow 4,096 characters, identities
+513 and details 1,024. A navigation intent has at most 16 parameters, with
+64-character keys and 4,096-character values. Requests bound cursors to 1,024
+characters and placement context to four keys with 256-character values.
+Declarations offer up to four unique parameters of kind Computer, repository or
+branch, and unique desktop sizes from S, M and L. An optional watch names an
+existing storage marker or binding change feed. Resource envelopes and row
+actions are not part of the contract.
+
+Decoders reject invalid wire values. Gill output is text data, never executable
+UI. Loading is host state. The client throws on HTTP errors unless the injected
+host decoder recognizes the refusal.
+
+## Contribute and license
+
+Run `pnpm build`, `pnpm typecheck`, `pnpm lint`, `pnpm test`, `pnpm docs` and
+`pnpm stranger` in this package. Regenerate API docs with `pnpm docs:write`.
+Licensed under [MIT](LICENSE).
+
+### Shared row time copy
+
+`relativeTime` from `@fungi.computer/gills/presentation` formats a reported
+millisecond timestamp using the Apps' existing English relative-time copy. This
+pure entry does not load the Gill decoder. Source methods keep their timestamps
+unchanged; a projection only formats timestamps its source returns.

package/dist/declaration.d.ts

@@ -0,0 +1,55 @@
+import * as Schema from "effect/Schema";
+/** Sizes the App explicitly offers for a desktop Gill. */
+export type AppGillDesktopSize = "S" | "M" | "L";
+/** One App-owned placement selector. */
+export type AppGillParam = Readonly<{
+    key: string;
+    label: string;
+    kind: "computer" | "repository" | "branch";
+    required: boolean;
+    /** This App's declared read method returning picker choices; Computers are host-owned. */
+    options?: string | undefined;
+}>;
+/** An existing change feed used to refresh a Gill. */
+export type AppGillWatch = Readonly<{
+    storage: string;
+} | {
+    binding: string;
+}>;
+/** A digest-covered projection of one declared read method. */
+export type AppDeclaredGill = Readonly<{
+    id: string;
+    source: string;
+    title: string;
+    params?: readonly AppGillParam[] | undefined;
+    watch?: AppGillWatch | undefined;
+    desktop?: Readonly<{
+        sizes: readonly AppGillDesktopSize[];
+    }> | undefined;
+}>;
+/** Bounded, App-owned parameter key. */
+export declare const appGillParamKeySchema: Schema.String;
+/** Placement parameter metadata, included in the Release digest. */
+export declare const appGillParamSchema: Schema.Struct<{
+    readonly key: Schema.String;
+    readonly label: Schema.String;
+    readonly kind: Schema.Literals<readonly ["computer", "repository", "branch"]>;
+    readonly required: Schema.Boolean;
+    readonly options: Schema.optional<Schema.String>;
+}>;
+/** The bounded, uniquely keyed placement parameters shared with desktop catalogs. */
+export declare const appGillParamsSchema: Schema.$Array<Schema.Struct<{
+    readonly key: Schema.String;
+    readonly label: Schema.String;
+    readonly kind: Schema.Literals<readonly ["computer", "repository", "branch"]>;
+    readonly required: Schema.Boolean;
+    readonly options: Schema.optional<Schema.String>;
+}>>;
+/** A storage marker or host binding's existing change feed. */
+export declare const appGillWatchSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly storage: Schema.String;
+}>, Schema.Struct<{
+    readonly binding: Schema.String;
+}>]>;
+/** Digest-covered identity, source, context and desktop sizes of a Gill. */
+export declare const appDeclaredGillSchema: Schema.Codec<AppDeclaredGill>;

package/dist/declaration.js

@@ -0,0 +1,41 @@
+import * as Schema from "effect/Schema";
+const isUnique = (values) => new Set(values).size === values.length;
+const meaningful = Schema.String.pipe(Schema.check(Schema.isMaxLength(256)), Schema.check(Schema.makeFilter((value) => value.trim().length > 0, {
+    message: "Declared command text must not be blank",
+})));
+/** Bounded, App-owned parameter key. */
+export const appGillParamKeySchema = meaningful.pipe(Schema.check(Schema.isMaxLength(64)));
+/** Placement parameter metadata, included in the Release digest. */
+export const appGillParamSchema = Schema.Struct({
+    key: appGillParamKeySchema,
+    label: meaningful,
+    kind: Schema.Literals(["computer", "repository", "branch"]),
+    required: Schema.Boolean,
+    options: Schema.optional(meaningful),
+}).check(Schema.makeFilter((param) => param.kind !== "computer" || param.options === undefined, {
+    message: "Computer options are host-owned",
+}));
+/** The bounded, uniquely keyed placement parameters shared with desktop catalogs. */
+export const appGillParamsSchema = Schema.Array(appGillParamSchema).check(Schema.isMaxLength(4), Schema.makeFilter((params) => isUnique(params.map((param) => param.key)), {
+    message: "Gill parameter keys must be unique",
+}));
+/** A storage marker or host binding's existing change feed. */
+export const appGillWatchSchema = Schema.Union([
+    Schema.Struct({ storage: meaningful }),
+    Schema.Struct({ binding: meaningful }),
+]);
+/** Digest-covered identity, source, context and desktop sizes of a Gill. */
+export const appDeclaredGillSchema = Schema.Struct({
+    id: meaningful.pipe(Schema.check(Schema.makeFilter((id) => !id.includes(":"), {
+        message: "Gill IDs are App-local",
+    }))),
+    title: meaningful,
+    source: meaningful,
+    params: Schema.optional(appGillParamsSchema),
+    watch: Schema.optional(appGillWatchSchema),
+    desktop: Schema.optional(Schema.Struct({
+        sizes: Schema.Array(Schema.Literals(["S", "M", "L"])).check(Schema.isMinLength(1), Schema.isMaxLength(3), Schema.makeFilter(isUnique, {
+            message: "Desktop Gill sizes must be unique",
+        })),
+    })),
+});

package/dist/gill.d.ts

@@ -0,0 +1,248 @@
+import * as Schema from "effect/Schema";
+import { type AppDeclaredGill } from "./declaration.js";
+/** Placement values are bounded; the admitting host checks declared keys. */
+export declare const gillParamsSchema: Schema.$Record<Schema.String, Schema.String>;
+/** The caller supplies placement context and a source-owned continuation. */
+export declare const gillRequestSchema: Schema.Struct<{
+    readonly viewId: Schema.String;
+    readonly params: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly after: Schema.optional<Schema.String>;
+    readonly options: Schema.optional<Schema.String>;
+}>;
+/** Selectors supplied by a Gill caller. */
+export type GillRequest = Schema.Schema.Type<typeof gillRequestSchema>;
+/** Runtime call selected by the host after admitting a declared source. */
+export declare const gillCallSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly params: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly after: Schema.optional<Schema.String>;
+    readonly options: Schema.optional<Schema.String>;
+}>;
+/** Input to the generated backend Gill entry. */
+export type GillCall = Schema.Schema.Type<typeof gillCallSchema>;
+/** Shared response codec. Rows are plain text and cannot carry executable UI. */
+export declare const gillResponseSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly viewId: Schema.String;
+    readonly title: Schema.String;
+    readonly state: Schema.Literal<"empty">;
+    readonly rows: Schema.Tuple<readonly []>;
+    readonly next: Schema.optional<Schema.String>;
+}>, Schema.Struct<{
+    readonly viewId: Schema.String;
+    readonly title: Schema.String;
+    readonly state: Schema.Literal<"error">;
+    readonly rows: Schema.Tuple<readonly []>;
+    /** Host-owned permanent execution refusal; an ordinary error may still be refreshed. */
+    readonly reason: Schema.optional<Schema.Literals<readonly ["exec_isolation_required", "params_required"]>>;
+    readonly error: Schema.String;
+    /** The host supplies the same-placement picker and this App's launch. */
+    readonly recovery: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"configure">;
+        readonly param: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"open">;
+    }>]>>;
+}>, Schema.Struct<{
+    readonly viewId: Schema.String;
+    readonly title: Schema.String;
+    readonly state: Schema.Literal<"full">;
+    readonly rows: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly title: Schema.String;
+        readonly detail: Schema.optional<Schema.String>;
+        readonly tone: Schema.optional<Schema.Literals<readonly ["attention", "running", "error", "settled", "muted"]>>;
+        readonly status: Schema.optional<Schema.Struct<{
+            readonly label: Schema.String;
+            readonly tone: Schema.Literals<readonly ["neutral", "primary", "secondary", "accent", "success", "info", "warning", "error"]>;
+        }>>;
+        readonly open: Schema.optional<Schema.Struct<{
+            readonly params: Schema.$Array<Schema.Struct<{
+                readonly key: Schema.String;
+                readonly value: Schema.String;
+            }>>;
+        }>>;
+    }>>;
+    readonly next: Schema.optional<Schema.String>;
+}>]>;
+/** A decoded page of plain-text Gill rows or a bounded error. */
+export type GillResponse = Schema.Schema.Type<typeof gillResponseSchema>;
+/** Decode backend output once at the App host boundary. */
+export declare const decodeGillResponse: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+    readonly state: "empty";
+    readonly title: string;
+    readonly viewId: string;
+    readonly rows: readonly [];
+    readonly next?: string | undefined;
+} | {
+    readonly error: string;
+    readonly state: "error";
+    readonly title: string;
+    readonly viewId: string;
+    readonly rows: readonly [];
+    readonly reason?: "exec_isolation_required" | "params_required" | undefined;
+    readonly recovery?: {
+        readonly kind: "configure";
+        readonly param: string;
+    } | {
+        readonly kind: "open";
+    } | undefined;
+} | {
+    readonly state: "full";
+    readonly title: string;
+    readonly viewId: string;
+    readonly rows: readonly {
+        readonly id: string;
+        readonly title: string;
+        readonly detail?: string | undefined;
+        readonly tone?: "error" | "running" | "attention" | "settled" | "muted" | undefined;
+        readonly open?: {
+            readonly params: readonly {
+                readonly key: string;
+                readonly value: string;
+            }[];
+        } | undefined;
+        readonly status?: {
+            readonly label: string;
+            readonly tone: "accent" | "error" | "success" | "neutral" | "primary" | "secondary" | "info" | "warning";
+        } | undefined;
+    }[];
+    readonly next?: string | undefined;
+};
+/** A bounded choice page returned by an App-owned options read method. */
+export declare const gillOptionsResponseSchema: Schema.Struct<{
+    readonly options: Schema.$Array<Schema.Struct<{
+        readonly value: Schema.String;
+        readonly label: Schema.String;
+        readonly detail: Schema.optional<Schema.String>;
+    }>>;
+    readonly next: Schema.optional<Schema.String>;
+}>;
+/** Choices remain within the selected App; the host supplies Computer choices. */
+export type GillOptionsResponse = Schema.Schema.Type<typeof gillOptionsResponseSchema>;
+/** Shared wire for a rows read or a placement-options read. */
+export declare const gillReplySchema: Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
+    readonly viewId: Schema.String;
+    readonly title: Schema.String;
+    readonly state: Schema.Literal<"empty">;
+    readonly rows: Schema.Tuple<readonly []>;
+    readonly next: Schema.optional<Schema.String>;
+}>, Schema.Struct<{
+    readonly viewId: Schema.String;
+    readonly title: Schema.String;
+    readonly state: Schema.Literal<"error">;
+    readonly rows: Schema.Tuple<readonly []>;
+    /** Host-owned permanent execution refusal; an ordinary error may still be refreshed. */
+    readonly reason: Schema.optional<Schema.Literals<readonly ["exec_isolation_required", "params_required"]>>;
+    readonly error: Schema.String;
+    /** The host supplies the same-placement picker and this App's launch. */
+    readonly recovery: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"configure">;
+        readonly param: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"open">;
+    }>]>>;
+}>, Schema.Struct<{
+    readonly viewId: Schema.String;
+    readonly title: Schema.String;
+    readonly state: Schema.Literal<"full">;
+    readonly rows: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly title: Schema.String;
+        readonly detail: Schema.optional<Schema.String>;
+        readonly tone: Schema.optional<Schema.Literals<readonly ["attention", "running", "error", "settled", "muted"]>>;
+        readonly status: Schema.optional<Schema.Struct<{
+            readonly label: Schema.String;
+            readonly tone: Schema.Literals<readonly ["neutral", "primary", "secondary", "accent", "success", "info", "warning", "error"]>;
+        }>>;
+        readonly open: Schema.optional<Schema.Struct<{
+            readonly params: Schema.$Array<Schema.Struct<{
+                readonly key: Schema.String;
+                readonly value: Schema.String;
+            }>>;
+        }>>;
+    }>>;
+    readonly next: Schema.optional<Schema.String>;
+}>]>, Schema.Struct<{
+    readonly options: Schema.$Array<Schema.Struct<{
+        readonly value: Schema.String;
+        readonly label: Schema.String;
+        readonly detail: Schema.optional<Schema.String>;
+    }>>;
+    readonly next: Schema.optional<Schema.String>;
+}>]>;
+/** A rows read or a placement-options read. */
+export type GillReply = Schema.Schema.Type<typeof gillReplySchema>;
+/** Decode the selected host's bounded reply before rendering or navigation. */
+export declare const decodeGillReply: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+    readonly state: "empty";
+    readonly title: string;
+    readonly viewId: string;
+    readonly rows: readonly [];
+    readonly next?: string | undefined;
+} | {
+    readonly error: string;
+    readonly state: "error";
+    readonly title: string;
+    readonly viewId: string;
+    readonly rows: readonly [];
+    readonly reason?: "exec_isolation_required" | "params_required" | undefined;
+    readonly recovery?: {
+        readonly kind: "configure";
+        readonly param: string;
+    } | {
+        readonly kind: "open";
+    } | undefined;
+} | {
+    readonly state: "full";
+    readonly title: string;
+    readonly viewId: string;
+    readonly rows: readonly {
+        readonly id: string;
+        readonly title: string;
+        readonly detail?: string | undefined;
+        readonly tone?: "error" | "running" | "attention" | "settled" | "muted" | undefined;
+        readonly open?: {
+            readonly params: readonly {
+                readonly key: string;
+                readonly value: string;
+            }[];
+        } | undefined;
+        readonly status?: {
+            readonly label: string;
+            readonly tone: "accent" | "error" | "success" | "neutral" | "primary" | "secondary" | "info" | "warning";
+        } | undefined;
+    }[];
+    readonly next?: string | undefined;
+} | {
+    readonly options: readonly {
+        readonly value: string;
+        readonly label: string;
+        readonly detail?: string | undefined;
+    }[];
+    readonly next?: string | undefined;
+};
+/** Decode an options method's result without trusting extra fields. */
+export declare const decodeGillOptionsResponse: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+    readonly options: readonly {
+        readonly value: string;
+        readonly label: string;
+        readonly detail?: string | undefined;
+    }[];
+    readonly next?: string | undefined;
+};
+/** App output must match its digest-covered view identity. */
+export declare function decodeDeclaredGillResponse(response: GillResponse, declaration: Pick<AppDeclaredGill, "id" | "params">): GillResponse;
+/** Authenticated host Fetch stays outside App code and is pinned to one selection. */
+export declare function createGillClient(options: Readonly<{
+    /** Decode a host's HTTP 503 body into its Gill refusal, if recognized. */
+    decodeRefusal?: (raw: Schema.Json, declaration: Readonly<{
+        id: string;
+        title: string;
+    }>) => GillResponse | undefined;
+    endpoint: string;
+    fetch: typeof globalThis.fetch;
+    declaration: Pick<AppDeclaredGill, "id" | "title" | "params">;
+}>): {
+    /** Fetch one decoded page using this client's pinned declaration. */
+    request(selectors: GillRequest, signal?: AbortSignal): Promise<GillReply>;
+};

package/dist/gill.js

@@ -0,0 +1,134 @@
+import * as Schema from "effect/Schema";
+import { appGillParamKeySchema } from "./declaration.js";
+import { rowLabelSchemaV1 as label, rowIdentitySchemaV1 as identity, rowPageSchemaV1 as rows, } from "./rows.js";
+/** Placement values are bounded; the admitting host checks declared keys. */
+export const gillParamsSchema = Schema.Record(appGillParamKeySchema, Schema.String.check(Schema.isMaxLength(256))).check(Schema.makeFilter((params) => Object.keys(params).length <= 4, {
+    message: "Gill placement supports at most four parameters",
+}));
+/** The caller supplies placement context and a source-owned continuation. */
+export const gillRequestSchema = Schema.Struct({
+    viewId: identity,
+    params: Schema.optional(gillParamsSchema),
+    after: Schema.optional(Schema.String.check(Schema.isMaxLength(1_024))),
+    options: Schema.optional(appGillParamKeySchema),
+});
+/** Runtime call selected by the host after admitting a declared source. */
+export const gillCallSchema = Schema.Struct({
+    id: identity,
+    params: Schema.optional(gillParamsSchema),
+    after: Schema.optional(Schema.String.check(Schema.isMaxLength(1_024))),
+    options: Schema.optional(appGillParamKeySchema),
+});
+/** Shared response codec. Rows are plain text and cannot carry executable UI. */
+export const gillResponseSchema = Schema.Union([
+    Schema.Struct({
+        viewId: identity,
+        title: label,
+        state: Schema.Literal("empty"),
+        rows: Schema.Tuple([]),
+        next: Schema.optional(Schema.String.pipe(Schema.check(Schema.isMaxLength(1_024)))),
+    }),
+    Schema.Struct({
+        viewId: identity,
+        title: label,
+        state: Schema.Literal("error"),
+        rows: Schema.Tuple([]),
+        /** Host-owned permanent execution refusal; an ordinary error may still be refreshed. */
+        reason: Schema.optional(Schema.Literals(["exec_isolation_required", "params_required"])),
+        error: Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(512))),
+        /** The host supplies the same-placement picker and this App's launch. */
+        recovery: Schema.optional(Schema.Union([
+            Schema.Struct({
+                kind: Schema.Literal("configure"),
+                param: appGillParamKeySchema,
+            }),
+            Schema.Struct({ kind: Schema.Literal("open") }),
+        ])),
+    }),
+    Schema.Struct({
+        viewId: identity,
+        title: label,
+        state: Schema.Literal("full"),
+        rows: rows.pipe(Schema.check(Schema.isMinLength(1))),
+        next: Schema.optional(Schema.String.pipe(Schema.check(Schema.isMaxLength(1_024)))),
+    }),
+]);
+/** Decode backend output once at the App host boundary. */
+export const decodeGillResponse = Schema.decodeUnknownSync(gillResponseSchema, {
+    onExcessProperty: "error",
+});
+/** A bounded choice page returned by an App-owned options read method. */
+export const gillOptionsResponseSchema = Schema.Struct({
+    options: Schema.Array(Schema.Struct({
+        value: Schema.String.check(Schema.isMaxLength(256)),
+        label,
+        detail: Schema.optional(Schema.String.check(Schema.isMaxLength(1_024))),
+    })).check(Schema.isMaxLength(200)),
+    next: Schema.optional(Schema.String.check(Schema.isMaxLength(1_024))),
+});
+/** Shared wire for a rows read or a placement-options read. */
+export const gillReplySchema = Schema.Union([
+    gillResponseSchema,
+    gillOptionsResponseSchema,
+]);
+/** Decode the selected host's bounded reply before rendering or navigation. */
+export const decodeGillReply = Schema.decodeUnknownSync(gillReplySchema, {
+    onExcessProperty: "error",
+});
+/** Decode an options method's result without trusting extra fields. */
+export const decodeGillOptionsResponse = Schema.decodeUnknownSync(gillOptionsResponseSchema, { onExcessProperty: "error" });
+/** App output must match its digest-covered view identity. */
+export function decodeDeclaredGillResponse(response, declaration) {
+    if (response.viewId !== declaration.id)
+        throw new Error("Gill response does not match its Release declaration");
+    const recovery = response.state === "error" ? response.recovery : undefined;
+    if (recovery?.kind === "configure" &&
+        !declaration.params?.some((param) => param.key === recovery.param))
+        throw new Error("Gill recovery parameter is not declared");
+    return response;
+}
+/** Authenticated host Fetch stays outside App code and is pinned to one selection. */
+export function createGillClient(options) {
+    return {
+        /** Fetch one decoded page using this client's pinned declaration. */
+        async request(selectors, signal) {
+            if (selectors.viewId !== options.declaration.id)
+                throw new Error("Gill request does not match its Release declaration");
+            const response = await options.fetch(options.endpoint, {
+                method: "PUT",
+                redirect: "error",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(Schema.encodeSync(gillRequestSchema)(selectors)),
+                signal: signal ?? null,
+            });
+            if (!response.ok) {
+                if (response.status === 503) {
+                    let raw;
+                    try {
+                        raw = Schema.decodeUnknownSync(Schema.Json)(await response.json());
+                    }
+                    catch (cause) {
+                        throw new Error("Gill request refused with HTTP 503", { cause });
+                    }
+                    const refusal = options.decodeRefusal?.(raw, options.declaration);
+                    if (refusal !== undefined)
+                        return refusal;
+                }
+                else {
+                    await response.body?.cancel();
+                }
+                throw new Error(`Gill request refused with HTTP ${String(response.status)}`);
+            }
+            const raw = await response.json();
+            const reply = decodeGillReply(raw);
+            if ("options" in reply) {
+                if (selectors.options === undefined)
+                    throw new Error("Gill returned choices for a row read");
+                return reply;
+            }
+            if (selectors.options !== undefined && reply.state !== "error")
+                throw new Error("Gill returned rows for an options read");
+            return decodeDeclaredGillResponse(reply, options.declaration);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./rows.js";
+export * from "./gill.js";
+export * from "./declaration.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./rows.js";
+export * from "./gill.js";
+export * from "./declaration.js";

package/dist/presentation.d.ts

@@ -0,0 +1,2 @@
+/** Render App timestamps using Bonsai's existing relative-time presentation. */
+export declare function relativeTime(at: number, now?: number): string;

package/dist/presentation.js

@@ -0,0 +1,20 @@
+const units = [
+    ["year", 31_536_000_000],
+    ["month", 2_592_000_000],
+    ["week", 604_800_000],
+    ["day", 86_400_000],
+    ["hour", 3_600_000],
+    ["minute", 60_000],
+];
+const relative = new Intl.RelativeTimeFormat("en", {
+    numeric: "auto",
+    style: "narrow",
+});
+/** Render App timestamps using Bonsai's existing relative-time presentation. */
+export function relativeTime(at, now = Date.now()) {
+    const delta = at - now;
+    for (const [unit, size] of units)
+        if (Math.abs(delta) >= size)
+            return relative.format(Math.round(delta / size), unit);
+    return "just now";
+}