For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

A browser send follows one path to the capability

Goal: trace one user action from a click to the server and back, and know which file owns each step.¶

Foldkit²⁷ is the browser UI framework in rat-stack. A Foldkit program keeps its state in a Model. Events arrive as Messages.¶

An update function takes the Model and a Message, and returns a new Model plus any Commands. A Command is a named task that runs outside update and ends by sending another Message.¶

The docs browser at /search is the worked example. Its search box calls the search capability²¹.¶

1. The view sends a Message

The Search button sends SubmittedSearch. The view does no fetching.¶

          Button.view(
            {
              onClick: Message.SubmittedSearch(),
              toView: ({ button }) => h.button(button, ["Search"]),
              type: "button",
            },

Every Message the program accepts is declared in one union:¶

export const Message = defineMessageUnion({
  ChangedUrl: { url: Url },
  ClickedLink: { request: UrlRequest },
  CompletedLoadExternal: {},
  CompletedNavigate: {},
  FailedRead: {
    generation: Schema.Finite,
    message: Schema.String,
    notFound: Schema.Boolean,
  },
  FailedSearch: { generation: Schema.Finite },
  SubmittedSearch: {},
  SucceededRead: { document: ReadOutput, generation: Schema.Finite },
  SucceededSearch: { generation: Schema.Finite, result: SearchOutput },
  UpdatedQuery: { value: Schema.String },
});

2. update returns a Command

update sets the search to Loading, increases a generation counter, and returns the SearchDocs Command:¶

const searchFor = (model: AppModel, query: string): DocsReturn => {
  const generation = model.generation + 1;

  return {
    commands: [SearchDocs({ generation, query })],
    model: { ...model, generation, query, search: SearchState.Loading() },
  };
};

update does no I/O. It describes the next Model and the work to run.¶

3. The Command calls the capability over RPC

export const SearchDocs = Command.define("SearchDocs", {
  args: { generation: Schema.Finite, query: Schema.String },
  execute: ({ query, generation }) =>
    DocumentQueries.use((queries) => queries.search(query)).pipe(
      Effect.map((result) => Message.SucceededSearch({ generation, result })),
      Effect.orElseSucceed(() => Message.FailedSearch({ generation }))
    ),
  messages: [Message.SucceededSearch, Message.FailedSearch],
});

DocumentQueries builds its RPC client from the shared contracts. The rat-stack-boundaries/no-browser-server-imports lint rule lets browser modules import @rat-stack/core/contracts and @rat-stack/capability/rpc-group, never a handler²⁸. AGENTS.md¶

const { group } = toRpcGroup([searchContract, readContract]);

const protocol = RpcClient.layerProtocolHttp({ url: "/rpc" }).pipe(
  Layer.provide([FetchHttpClient.layer, RpcSerialization.layerJson])
);

DocumentQueries keeps each search result for 30 seconds. A repeated query in that window is answered from the cache, with no fresh RPC. The RPC call runs on a cache miss:¶

  const search = yield* Cache.make({
    capacity: Number.POSITIVE_INFINITY,
    lookup: (query: string) => client.search({ limit: 10, query }),
    timeToLive: "30 seconds",
  });

On the server, implement binds the same searchContract to the content store:¶

export const search = implement(searchContract, ({ limit, query }) =>
  ContentStore.use((store) => store.search(query, limit)).pipe(
    Effect.map((matches) => ({ matches, total: matches.length }))
  )
);

4. update folds the result into the Model

    SucceededSearch: ({ generation, result }) => ({
      model:
        generation === model.generation
          ? { ...model, search: SearchState.Loaded({ result }) }
          : model,
    }),

The generation check drops a stale reply. If the user searches twice, the first reply carries an old generation, and update keeps the Model unchanged.¶

Why one path

Each step has one owner, so each step can be tested alone.¶

• The Model is data. The view reads it and sends Messages.¶
• update is a function of the Model and a Message. It runs without a network.¶
• In this program, only Commands call DocumentQueries, the RPC client. Each Command ends in a Message.¶
• The contract is the one Schema³⁰ set that the browser and the server share.¶

SearchState names four states: Idle, Loading, Loaded, and Failed. The view matches on all four, so no flag combination can show a spinner and an error at once. model.ts¶

Next

Read UI behaviour is a scene⁸ to test this program without a browser. Then read One capability, every surface²¹ for the server half of the contract.¶

CAFE²⁷ names where Foldkit sits in the stack.¶

Last changed 2026-11-08 in b8f4ccf. Source on GitHub. Change log.