@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/web-react/async/index.d.ts

@@ -1,309 +1,17 @@
-import { ReactElement, ReactNode } from 'react';
-
 /**
- * The fetch-state contract: a failed load cannot render as empty data.
+ * `web-react/async` — the three-state fetch primitive.
  *
- * Three shapes produce that defect, and two audited verticals shipped dozens of
- * each: a `catch` handler that only clears a loading flag, an early return on a
- * non-ok response, and a bare `null` returned while loading. All three end with
- * the same pixels a successful-but-empty load produces — "No templates
- * available", an empty member list, a blank conversation — so the reader cannot
- * tell "we asked and there is nothing" from "we could not ask", and the retry
- * that would fix it is never offered.
+ * A failed load, an empty result and a load in flight are three different
+ * things, and every product that hand-rolled them collapsed the first two: a
+ * network failure rendered as "No templates available", an empty member list or
+ * a blank conversation, with no message and no retry. The write half collapsed
+ * the same way in the other direction — a save button reading "Saved" over a
+ * 404, because a resolved promise was read as a landed write.
  *
- * `AsyncResourceState` makes the two outcomes separate variants: `error` is the
- * only one carrying a message and it is never reachable with a value, `empty` is
- * the only one carrying a resolved-but-empty value and it never carries a
- * message. A component rendering one is structurally not rendering the other.
- *
- * This file is React-free so the state model, the emptiness rule and the
- * Response readers can be unit-tested and reused outside a component.
- */
-/**
- * - `idle` — no load has been attempted (the hook is disabled, or its inputs
- *   are not resolved yet). Distinct from `loading`: nothing is in flight.
- * - `loading` — a load is in flight and no value is held.
- * - `error` — the load failed. Carries the message and never a value.
- * - `empty` — the load succeeded and the value is empty. Never carries a message.
- * - `ready` — the load succeeded and the value is non-empty.
- */
-type AsyncResourceStatus = 'idle' | 'loading' | 'error' | 'empty' | 'ready';
-/** Re-runs the load. Present on every variant so the error branch can never be
- *  rendered without the action that recovers from it. */
-interface AsyncRetryable {
-    readonly retry: () => void;
-}
-type AsyncResourceState<T> = ({
-    readonly status: 'idle';
-} & AsyncRetryable) | ({
-    readonly status: 'loading';
-} & AsyncRetryable) | ({
-    readonly status: 'error';
-    readonly message: string;
-    readonly error: unknown;
-} & AsyncRetryable) | ({
-    readonly status: 'empty';
-    readonly value: T;
-} & AsyncRetryable) | ({
-    readonly status: 'ready';
-    readonly value: T;
-} & AsyncRetryable);
-/** The state model without the retry action — what a reducer produces. */
-type AsyncResolution<T> = {
-    readonly status: 'idle';
-} | {
-    readonly status: 'loading';
-} | {
-    readonly status: 'error';
-    readonly message: string;
-    readonly error: unknown;
-} | {
-    readonly status: 'empty';
-    readonly value: T;
-} | {
-    readonly status: 'ready';
-    readonly value: T;
-};
-declare const DEFAULT_ASYNC_ERROR_MESSAGE = "Something went wrong. Please try again.";
-/**
- * Default emptiness rule: `null`/`undefined`, an empty array, an empty `Map` or
- * `Set`. A string, a number and a plain object are `ready` — `''` and `{}` are
- * legitimate values for the resources that produce them, and guessing otherwise
- * would route a real answer into the empty branch. Pass `isEmpty` for a shape
- * this cannot see into (`{ items: [] }`, a paged envelope, a count).
- */
-declare function defaultIsEmpty(value: unknown): boolean;
-/** Best available human-readable message for a thrown value. Never returns an
- *  empty string — a blank error block reads as a rendering bug. */
-declare function asyncErrorMessage(error: unknown, fallback?: string): string;
-/** Classifies a successfully loaded value into `ready` or `empty`. */
-declare function resolveAsyncValue<T>(value: T, isEmpty?: (value: T) => boolean): AsyncResolution<T>;
-/**
- * A non-ok HTTP response, as a throwable. `requireOk`/`readOkJson` raise this so
- * a non-ok response reaches the `error` branch instead of an early `return` that
- * leaves the caller rendering the empty branch.
- */
-declare class AsyncRequestError extends Error {
-    readonly status: number;
-    readonly statusText: string;
-    readonly url: string;
-    /** First 200 characters of the response body when it could be read, else `''`.
-     *  Kept off `message` so a server's HTML error page never becomes UI copy. */
-    readonly body: string;
-    constructor(response: {
-        status: number;
-        statusText?: string;
-        url?: string;
-    }, body?: string);
-}
-/** Returns the response when ok; throws `AsyncRequestError` otherwise. Reads the
- *  body only on the failure path, so the caller keeps an unconsumed stream. */
-declare function requireOk(response: Response): Promise<Response>;
-/**
- * `requireOk` + `response.json()`. Without `parse` the result is `unknown`, so a
- * caller narrows at the JSON boundary rather than inheriting an unchecked shape;
- * with `parse` the validator runs inside the load and a rejection lands in the
- * `error` branch.
- */
-declare function readOkJson(response: Response): Promise<unknown>;
-declare function readOkJson<T>(response: Response, parse: (data: unknown) => T): Promise<T>;
-
-interface AsyncLoadContext {
-    /** Aborted when the inputs change, a retry supersedes this load, or the
-     *  component unmounts. Forward it to `fetch` so a superseded request stops. */
-    readonly signal: AbortSignal;
-}
-interface UseAsyncResourceOptions<T> {
-    /**
-     * The one load. Reject (or throw) to reach the `error` branch — a non-ok
-     * response must reject too, which is what `requireOk`/`readOkJson` are for.
-     * Read from a ref internally, so an inline arrow does not re-trigger; `deps`
-     * is what declares when the load must run again.
-     */
-    load: (context: AsyncLoadContext) => Promise<T>;
-    /** Re-runs the load when any entry changes by `Object.is`, like `useEffect`. */
-    deps?: readonly unknown[];
-    /** `false` holds the resource at `idle` and runs nothing — for inputs that are
-     *  not resolved yet. Flipping it to `true` starts the load. */
-    enabled?: boolean;
-    /** First-render seed (an SSR/loader page). The hook starts resolved and skips
-     *  the first load. Read once — later identity changes are ignored, so a
-     *  revalidating loader belongs in `deps`, not here. */
-    initialValue?: T;
-    /** Splits a successful load into `empty` vs `ready`. Default: `defaultIsEmpty`. */
-    isEmpty?: (value: T) => boolean;
-    /** Maps a thrown value to the message the `error` branch renders. */
-    errorMessage?: (error: unknown) => string;
-}
-/**
- * The five-state fetch machine: `idle | loading | error | empty | ready`.
- *
- * What it guarantees, and what the hand-rolled versions it replaces did not:
- *
- * - a rejected load lands on `error` with a message and a `retry`, never on an
- *   empty list;
- * - `empty` is only reachable from a load that actually succeeded;
- * - a superseded load (inputs changed, retry pressed, component unmounted) is
- *   aborted and its late result is dropped by a monotonic sequence guard, so it
- *   cannot repaint a newer view.
- */
-declare function useAsyncResource<T>({ load, deps, enabled, initialValue, isEmpty, errorMessage, }: UseAsyncResourceOptions<T>): AsyncResourceState<T>;
-
-/**
- * The brand that makes "Saved" unreachable without a confirmed write.
- *
- * A resolved promise is not a success: `fetch` resolves on a 404, and the
- * shipped defect this closes is a save button that rendered "Saved" because the
- * only thing awaited was that the request came back at all. The success variant
- * therefore carries a symbol no object literal can spell, so the only way into
- * `succeeded` is `confirmWrite` / `confirmResponse` / `confirmJson` — each of
- * which has already checked that the write landed.
- */
-declare const CONFIRMED_WRITE: unique symbol;
-interface MutationConfirmed<T> {
-    readonly succeeded: true;
-    readonly value: T;
-    readonly [CONFIRMED_WRITE]: true;
-}
-interface MutationRejected {
-    readonly succeeded: false;
-    /** Safe to render: what the user is told the write did not do. */
-    readonly message: string;
-    readonly error?: unknown;
-}
-type MutationOutcome<T> = MutationConfirmed<T> | MutationRejected;
-/** Confirms a write whose success is already established (an SDK call that
- *  throws on failure, a store returning its own typed outcome). The deliberate
- *  act is the point — this call is what an audit greps for. */
-declare function confirmWrite<T>(value: T): MutationConfirmed<T>;
-/** A write that did not land. Constructible by hand: failing loud is never the
- *  direction that needs guarding. */
-declare function rejectWrite(message: string, error?: unknown): MutationRejected;
-/** Confirms only a 2xx response. A 404/500 becomes a rejection carrying the
- *  status — never a success, whatever the promise did. */
-declare function confirmResponse(response: Response): Promise<MutationOutcome<Response>>;
-/** `confirmResponse` + a JSON body. A non-ok status, an unreadable body and a
- *  throwing `parse` are all rejections. */
-declare function confirmJson<T>(response: Response, parse: (data: unknown) => T): Promise<MutationOutcome<T>>;
-/** True only for a value built by one of the confirm helpers. Takes `unknown`
- *  because an untyped consumer can return anything from `mutate`. */
-declare function isConfirmedWrite<T>(outcome: unknown): outcome is MutationConfirmed<T>;
-type MutationState<T> = {
-    readonly status: 'idle';
-} | {
-    readonly status: 'pending';
-} | {
-    readonly status: 'succeeded';
-    readonly value: T;
-} | {
-    readonly status: 'failed';
-    readonly message: string;
-    readonly error: unknown;
-};
-interface UseConfirmedMutationOptions<TInput, TValue> {
-    /**
-     * Performs the write and returns a confirmation. Anything else — including a
-     * hand-written `{ succeeded: true }` — is treated as a failed write, because
-     * an unbranded object is exactly the shape produced by code that never
-     * checked the response.
-     *
-     * The context signal aborts only when a later `run` supersedes this one. It is
-     * NOT aborted on unmount: a write the user asked for must not be cancelled by
-     * navigating away.
-     */
-    mutate: (input: TInput, context: AsyncLoadContext) => Promise<MutationOutcome<TValue>>;
-    /** Fires after the state reaches `succeeded` (latest run only). */
-    onSucceeded?: (value: TValue) => void;
-    /** Fires after the state reaches `failed` (latest run only). */
-    onFailed?: (message: string, error: unknown) => void;
-    /** Maps a thrown value to the message the `failed` state renders. */
-    errorMessage?: (error: unknown) => string;
-}
-interface ConfirmedMutation<TInput, TValue> {
-    readonly state: MutationState<TValue>;
-    /** Runs the write. Never rejects — the outcome is returned and mirrored into
-     *  `state`. Concurrent runs are last-write-wins; disable the control while
-     *  `state.status === 'pending'`. */
-    readonly run: (input: TInput) => Promise<MutationOutcome<TValue>>;
-    /** Back to `idle` (dismisses a "Saved" or error affordance). */
-    readonly reset: () => void;
-}
-/**
- * `idle | pending | succeeded | failed` over a write that must confirm itself.
- *
- * `succeeded` is reachable only through a branded confirmation, so the audited
- * "Saved on a 404" bug cannot be written with this hook: the 404 path produces
- * `failed` carrying the status, and a `mutate` that forgot to check produces
- * `failed` carrying the contract violation rather than a success it never
- * earned.
- */
-declare function useConfirmedMutation<TInput, TValue>({ mutate, onSucceeded, onFailed, errorMessage, }: UseConfirmedMutationOptions<TInput, TValue>): ConfirmedMutation<TInput, TValue>;
-
-interface AsyncEmptyAction {
-    label: string;
-    onClick: () => void;
-}
-interface AsyncEmptySpec {
-    /** What is not there, in the reader's words ("No templates yet"). Required:
-     *  an empty state with nothing to say is the state this module exists to
-     *  stop being mistaken for a failure. */
-    title: string;
-    description?: string;
-    /** The next action. An element is rendered as supplied (a link, a dialog
-     *  trigger); the object form renders the standard button. */
-    action?: AsyncEmptyAction | ReactElement;
-}
-interface AsyncErrorRenderProps {
-    message: string;
-    retry: () => void;
-}
-interface AsyncViewProps<T> {
-    state: AsyncResourceState<T>;
-    /** Rendered only for `ready`, with the loaded value — the branch cannot be
-     *  entered without one. */
-    children: (value: T) => ReactNode;
-    /** Required: `empty` must name what is missing and what to do about it. */
-    empty: AsyncEmptySpec | ReactElement;
-    /** Must return an element. Returning nothing is what produced the blank
-     *  screens this component replaces, so a nullish return falls back to the
-     *  built-in block rather than rendering nothing. */
-    renderLoading?: () => ReactElement;
-    renderError?: (props: AsyncErrorRenderProps) => ReactElement;
-    /** `idle` renders the loading block by default — from the reader's side,
-     *  "not started" and "in flight" are the same wait. */
-    renderIdle?: () => ReactElement;
-    loadingLabel?: string;
-    retryLabel?: string;
-    /** Applied to the wrapper around the non-`ready` branches. `ready` renders the
-     *  children with no wrapper element, so grids and lists keep their layout. */
-    className?: string;
-}
-/**
- * Renders the branch the state is actually in.
- *
- * The three anti-patterns this replaces (`catch` that only clears a loading
- * flag, early return on a non-ok response, bare `null` while loading) all end at
- * the same rendered output as a successful-but-empty load. Here every branch is
- * reached from a different variant and each renders visibly: `loading` and
- * `idle` render a labelled busy block, `error` renders the message plus the
- * retry, `empty` renders the caller's copy and next action, and `ready` is the
- * only branch with a value to hand to `children`.
- */
-declare function AsyncView<T>({ state, children, empty, renderLoading, renderError, renderIdle, loadingLabel, retryLabel, className, }: AsyncViewProps<T>): ReactElement;
-interface MutationStatusLabels {
-    pending?: string;
-    succeeded?: string;
-}
-interface MutationStatusProps<T> {
-    state: MutationState<T>;
-    labels?: MutationStatusLabels;
-    className?: string;
-}
-/**
- * The write's own status line. "Saved" renders only from `succeeded`, which
- * `useConfirmedMutation` can only reach through a confirmed write, so the label
- * cannot appear over a failed request.
+ * Adoption, with the before/after for each shape:
+ * [`docs/async-state-module.md`](../../../docs/async-state-module.md).
  */
-declare function MutationStatus<T>({ state, labels, className }: MutationStatusProps<T>): ReactElement | null;
-
-export { type AsyncEmptyAction, type AsyncEmptySpec, type AsyncErrorRenderProps, type AsyncLoadContext, AsyncRequestError, type AsyncResolution, type AsyncResourceState, type AsyncResourceStatus, type AsyncRetryable, AsyncView, type AsyncViewProps, CONFIRMED_WRITE, type ConfirmedMutation, DEFAULT_ASYNC_ERROR_MESSAGE, type MutationConfirmed, type MutationOutcome, type MutationRejected, type MutationState, MutationStatus, type MutationStatusLabels, type MutationStatusProps, type UseAsyncResourceOptions, type UseConfirmedMutationOptions, asyncErrorMessage, confirmJson, confirmResponse, confirmWrite, defaultIsEmpty, isConfirmedWrite, readOkJson, rejectWrite, requireOk, resolveAsyncValue, useAsyncResource, useConfirmedMutation };
+export { AsyncRequestError, DEFAULT_ASYNC_ERROR_MESSAGE, asyncErrorMessage, defaultIsEmpty, readOkJson, requireOk, resolveAsyncValue, type AsyncResolution, type AsyncResourceState, type AsyncResourceStatus, type AsyncRetryable, } from './state';
+export { useAsyncResource, type AsyncLoadContext, type UseAsyncResourceOptions } from './use-async-resource';
+export { CONFIRMED_WRITE, confirmJson, confirmResponse, confirmWrite, isConfirmedWrite, rejectWrite, useConfirmedMutation, type ConfirmedMutation, type MutationConfirmed, type MutationOutcome, type MutationRejected, type MutationState, type UseConfirmedMutationOptions, } from './use-confirmed-mutation';
+export { AsyncView, MutationStatus, type AsyncEmptyAction, type AsyncEmptySpec, type AsyncErrorRenderProps, type AsyncViewProps, type MutationStatusLabels, type MutationStatusProps, } from './async-view';

package/dist/web-react/async/state.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The fetch-state contract: a failed load cannot render as empty data.
+ *
+ * Three shapes produce that defect, and two audited verticals shipped dozens of
+ * each: a `catch` handler that only clears a loading flag, an early return on a
+ * non-ok response, and a bare `null` returned while loading. All three end with
+ * the same pixels a successful-but-empty load produces — "No templates
+ * available", an empty member list, a blank conversation — so the reader cannot
+ * tell "we asked and there is nothing" from "we could not ask", and the retry
+ * that would fix it is never offered.
+ *
+ * `AsyncResourceState` makes the two outcomes separate variants: `error` is the
+ * only one carrying a message and it is never reachable with a value, `empty` is
+ * the only one carrying a resolved-but-empty value and it never carries a
+ * message. A component rendering one is structurally not rendering the other.
+ *
+ * This file is React-free so the state model, the emptiness rule and the
+ * Response readers can be unit-tested and reused outside a component.
+ */
+/**
+ * - `idle` — no load has been attempted (the hook is disabled, or its inputs
+ *   are not resolved yet). Distinct from `loading`: nothing is in flight.
+ * - `loading` — a load is in flight and no value is held.
+ * - `error` — the load failed. Carries the message and never a value.
+ * - `empty` — the load succeeded and the value is empty. Never carries a message.
+ * - `ready` — the load succeeded and the value is non-empty.
+ */
+export type AsyncResourceStatus = 'idle' | 'loading' | 'error' | 'empty' | 'ready';
+/** Re-runs the load. Present on every variant so the error branch can never be
+ *  rendered without the action that recovers from it. */
+export interface AsyncRetryable {
+    readonly retry: () => void;
+}
+export type AsyncResourceState<T> = ({
+    readonly status: 'idle';
+} & AsyncRetryable) | ({
+    readonly status: 'loading';
+} & AsyncRetryable) | ({
+    readonly status: 'error';
+    readonly message: string;
+    readonly error: unknown;
+} & AsyncRetryable) | ({
+    readonly status: 'empty';
+    readonly value: T;
+} & AsyncRetryable) | ({
+    readonly status: 'ready';
+    readonly value: T;
+} & AsyncRetryable);
+/** The state model without the retry action — what a reducer produces. */
+export type AsyncResolution<T> = {
+    readonly status: 'idle';
+} | {
+    readonly status: 'loading';
+} | {
+    readonly status: 'error';
+    readonly message: string;
+    readonly error: unknown;
+} | {
+    readonly status: 'empty';
+    readonly value: T;
+} | {
+    readonly status: 'ready';
+    readonly value: T;
+};
+export declare const DEFAULT_ASYNC_ERROR_MESSAGE = "Something went wrong. Please try again.";
+/**
+ * Default emptiness rule: `null`/`undefined`, an empty array, an empty `Map` or
+ * `Set`. A string, a number and a plain object are `ready` — `''` and `{}` are
+ * legitimate values for the resources that produce them, and guessing otherwise
+ * would route a real answer into the empty branch. Pass `isEmpty` for a shape
+ * this cannot see into (`{ items: [] }`, a paged envelope, a count).
+ */
+export declare function defaultIsEmpty(value: unknown): boolean;
+/** Best available human-readable message for a thrown value. Never returns an
+ *  empty string — a blank error block reads as a rendering bug. */
+export declare function asyncErrorMessage(error: unknown, fallback?: string): string;
+/** Classifies a successfully loaded value into `ready` or `empty`. */
+export declare function resolveAsyncValue<T>(value: T, isEmpty?: (value: T) => boolean): AsyncResolution<T>;
+/**
+ * A non-ok HTTP response, as a throwable. `requireOk`/`readOkJson` raise this so
+ * a non-ok response reaches the `error` branch instead of an early `return` that
+ * leaves the caller rendering the empty branch.
+ */
+export declare class AsyncRequestError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly url: string;
+    /** First 200 characters of the response body when it could be read, else `''`.
+     *  Kept off `message` so a server's HTML error page never becomes UI copy. */
+    readonly body: string;
+    constructor(response: {
+        status: number;
+        statusText?: string;
+        url?: string;
+    }, body?: string);
+}
+/** Returns the response when ok; throws `AsyncRequestError` otherwise. Reads the
+ *  body only on the failure path, so the caller keeps an unconsumed stream. */
+export declare function requireOk(response: Response): Promise<Response>;
+/**
+ * `requireOk` + `response.json()`. Without `parse` the result is `unknown`, so a
+ * caller narrows at the JSON boundary rather than inheriting an unchecked shape;
+ * with `parse` the validator runs inside the load and a rejection lands in the
+ * `error` branch.
+ */
+export declare function readOkJson(response: Response): Promise<unknown>;
+export declare function readOkJson<T>(response: Response, parse: (data: unknown) => T): Promise<T>;

package/dist/web-react/async/use-async-resource.d.ts

@@ -0,0 +1,41 @@
+import { type AsyncResourceState } from './state';
+export interface AsyncLoadContext {
+    /** Aborted when the inputs change, a retry supersedes this load, or the
+     *  component unmounts. Forward it to `fetch` so a superseded request stops. */
+    readonly signal: AbortSignal;
+}
+export interface UseAsyncResourceOptions<T> {
+    /**
+     * The one load. Reject (or throw) to reach the `error` branch — a non-ok
+     * response must reject too, which is what `requireOk`/`readOkJson` are for.
+     * Read from a ref internally, so an inline arrow does not re-trigger; `deps`
+     * is what declares when the load must run again.
+     */
+    load: (context: AsyncLoadContext) => Promise<T>;
+    /** Re-runs the load when any entry changes by `Object.is`, like `useEffect`. */
+    deps?: readonly unknown[];
+    /** `false` holds the resource at `idle` and runs nothing — for inputs that are
+     *  not resolved yet. Flipping it to `true` starts the load. */
+    enabled?: boolean;
+    /** First-render seed (an SSR/loader page). The hook starts resolved and skips
+     *  the first load. Read once — later identity changes are ignored, so a
+     *  revalidating loader belongs in `deps`, not here. */
+    initialValue?: T;
+    /** Splits a successful load into `empty` vs `ready`. Default: `defaultIsEmpty`. */
+    isEmpty?: (value: T) => boolean;
+    /** Maps a thrown value to the message the `error` branch renders. */
+    errorMessage?: (error: unknown) => string;
+}
+/**
+ * The five-state fetch machine: `idle | loading | error | empty | ready`.
+ *
+ * What it guarantees, and what the hand-rolled versions it replaces did not:
+ *
+ * - a rejected load lands on `error` with a message and a `retry`, never on an
+ *   empty list;
+ * - `empty` is only reachable from a load that actually succeeded;
+ * - a superseded load (inputs changed, retry pressed, component unmounted) is
+ *   aborted and its late result is dropped by a monotonic sequence guard, so it
+ *   cannot repaint a newer view.
+ */
+export declare function useAsyncResource<T>({ load, deps, enabled, initialValue, isEmpty, errorMessage, }: UseAsyncResourceOptions<T>): AsyncResourceState<T>;

package/dist/web-react/async/use-confirmed-mutation.d.ts

@@ -0,0 +1,90 @@
+import type { AsyncLoadContext } from './use-async-resource';
+/**
+ * The brand that makes "Saved" unreachable without a confirmed write.
+ *
+ * A resolved promise is not a success: `fetch` resolves on a 404, and the
+ * shipped defect this closes is a save button that rendered "Saved" because the
+ * only thing awaited was that the request came back at all. The success variant
+ * therefore carries a symbol no object literal can spell, so the only way into
+ * `succeeded` is `confirmWrite` / `confirmResponse` / `confirmJson` — each of
+ * which has already checked that the write landed.
+ */
+export declare const CONFIRMED_WRITE: unique symbol;
+export interface MutationConfirmed<T> {
+    readonly succeeded: true;
+    readonly value: T;
+    readonly [CONFIRMED_WRITE]: true;
+}
+export interface MutationRejected {
+    readonly succeeded: false;
+    /** Safe to render: what the user is told the write did not do. */
+    readonly message: string;
+    readonly error?: unknown;
+}
+export type MutationOutcome<T> = MutationConfirmed<T> | MutationRejected;
+/** Confirms a write whose success is already established (an SDK call that
+ *  throws on failure, a store returning its own typed outcome). The deliberate
+ *  act is the point — this call is what an audit greps for. */
+export declare function confirmWrite<T>(value: T): MutationConfirmed<T>;
+/** A write that did not land. Constructible by hand: failing loud is never the
+ *  direction that needs guarding. */
+export declare function rejectWrite(message: string, error?: unknown): MutationRejected;
+/** Confirms only a 2xx response. A 404/500 becomes a rejection carrying the
+ *  status — never a success, whatever the promise did. */
+export declare function confirmResponse(response: Response): Promise<MutationOutcome<Response>>;
+/** `confirmResponse` + a JSON body. A non-ok status, an unreadable body and a
+ *  throwing `parse` are all rejections. */
+export declare function confirmJson<T>(response: Response, parse: (data: unknown) => T): Promise<MutationOutcome<T>>;
+/** True only for a value built by one of the confirm helpers. Takes `unknown`
+ *  because an untyped consumer can return anything from `mutate`. */
+export declare function isConfirmedWrite<T>(outcome: unknown): outcome is MutationConfirmed<T>;
+export type MutationState<T> = {
+    readonly status: 'idle';
+} | {
+    readonly status: 'pending';
+} | {
+    readonly status: 'succeeded';
+    readonly value: T;
+} | {
+    readonly status: 'failed';
+    readonly message: string;
+    readonly error: unknown;
+};
+export interface UseConfirmedMutationOptions<TInput, TValue> {
+    /**
+     * Performs the write and returns a confirmation. Anything else — including a
+     * hand-written `{ succeeded: true }` — is treated as a failed write, because
+     * an unbranded object is exactly the shape produced by code that never
+     * checked the response.
+     *
+     * The context signal aborts only when a later `run` supersedes this one. It is
+     * NOT aborted on unmount: a write the user asked for must not be cancelled by
+     * navigating away.
+     */
+    mutate: (input: TInput, context: AsyncLoadContext) => Promise<MutationOutcome<TValue>>;
+    /** Fires after the state reaches `succeeded` (latest run only). */
+    onSucceeded?: (value: TValue) => void;
+    /** Fires after the state reaches `failed` (latest run only). */
+    onFailed?: (message: string, error: unknown) => void;
+    /** Maps a thrown value to the message the `failed` state renders. */
+    errorMessage?: (error: unknown) => string;
+}
+export interface ConfirmedMutation<TInput, TValue> {
+    readonly state: MutationState<TValue>;
+    /** Runs the write. Never rejects — the outcome is returned and mirrored into
+     *  `state`. Concurrent runs are last-write-wins; disable the control while
+     *  `state.status === 'pending'`. */
+    readonly run: (input: TInput) => Promise<MutationOutcome<TValue>>;
+    /** Back to `idle` (dismisses a "Saved" or error affordance). */
+    readonly reset: () => void;
+}
+/**
+ * `idle | pending | succeeded | failed` over a write that must confirm itself.
+ *
+ * `succeeded` is reachable only through a branded confirmation, so the audited
+ * "Saved on a 404" bug cannot be written with this hook: the 404 path produces
+ * `failed` carrying the status, and a `mutate` that forgot to check produces
+ * `failed` carrying the contract violation rather than a success it never
+ * earned.
+ */
+export declare function useConfirmedMutation<TInput, TValue>({ mutate, onSucceeded, onFailed, errorMessage, }: UseConfirmedMutationOptions<TInput, TValue>): ConfirmedMutation<TInput, TValue>;

package/dist/web-react/brand-mark.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Load the canonical Tangle knot only when a web surface renders it.
+ * `/brand` imports the optional `@tangle-network/brand` peer, so a failed load
+ * renders a fixed-size spacer instead of crashing the chat shell.
+ */
+interface BrandMarkProps {
+    size?: number;
+    className?: string;
+}
+export declare function BrandMark({ size, className }: BrandMarkProps): import("react").JSX.Element;
+export {};

package/dist/web-react/chat-attachments.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Transcript-side counterpart to the composer's store-backed attachment
+ * primitive (agent-app#224). Unlike a `@`-mention, an attachment never rides
+ * inline in message text as a token to segment — it renders as its own
+ * card/chip keyed off the message's `parts`, so this module is just the
+ * browser-safe read side of the attachment vocabulary: the type guard, the
+ * per-message part filter, and the two pure conversions a composer/transcript
+ * needs before or after a byte upload.
+ *
+ * `ChatAttachmentPart` and its helpers are re-exported here from
+ * `../chat-store/parts` directly (not the `/chat-store` barrel), so a browser
+ * bundle gets the attachment vocabulary without importing `/chat-store`, whose
+ * barrel pulls the drizzle peer — same reasoning as `./chat-mentions`.
+ * `ChatAttachmentKind`/`ChatAttachmentInput` are NOT re-exported from here:
+ * they already ship from `./chat-stream` (the import-free `/chat-routes/wire`
+ * layer they're defined in), and re-exporting them again from here would
+ * collide across the two `export *`s in `./index`.
+ */
+import { attachmentInputToPart, attachmentKindForMime, attachmentPartKey, attachmentPartsFromMessageParts, isChatAttachmentPart, type ChatAttachmentPart } from '../chat-store/parts';
+export type { ChatAttachmentPart };
+export { attachmentInputToPart, attachmentKindForMime, attachmentPartKey, attachmentPartsFromMessageParts, isChatAttachmentPart };