Client Entrypoint

---
name: client-entrypoint
description: Bind shared entrypoint protocols in a client context with typed call(), invoke(), url(), bindAll(), and bindScreen(). Load when wiring client API routes or screens.
user-invocable: false
---

# @owlmeans/client-entrypoint

**Install:** `bun add @owlmeans/client-entrypoint@^0.1.18-rc.48`

Bind a declaration from `@owlmeans/entrypoint`; never construct or replace a contextual
entrypoint by alias.

```ts
import { bind, bindAll, bindScreen } from '@owlmeans/client-entrypoint'

context.registerEntrypoints(bindAll(projectProtocols))
context.registerEntrypoint(bind(projectProtocols.health))
context.registerEntrypoint(bindScreen(projectProtocols.home, handler(Home)))

const value = await context.entrypoint(projectProtocols.create).call({ body })
const { value, outcome } = await context.entrypoint(projectProtocols.create).invoke({ body })
const href = await context.entrypoint(projectProtocols.edit).url({ params: { id } })
```

`bindAll(tree)` flattens a nested named declaration tree while preserving the union of its protocol
types. `bind(protocol)` is appropriate where one protocol must use a distinct client option.
`bindScreen` is for a frontend route and renderer; screens are addressed by `url` and reject
`call`/`invoke`.

`bindScreen` takes a `lazyHandler(...)` result (`@owlmeans/client`) directly, the same as
`handler(Component)`: both return a `RefedEntrypointHandler`, the lazy one also carrying
`.preload()`, so no different wiring is needed. Create it at module scope, never in a render.

```ts
const reports = lazyHandler(() => import('./reports.js'), 'Reports', { fallback: <Spinner /> })
context.registerEntrypoint(bindScreen(projectProtocols.reports, reports))
```

`context.entrypoint(protocol)` derives `ClientProtocolEntrypoint<Protocol>` from the protocol. Do
not add an explicit result generic. `entrypointRef<Request, Response>(alias)` is reserved for a
dynamic remote declaration that cannot be imported.

Client calls include only contract request sections plus `CallOptions` (`auth`, host/port/base,
timeout, signal). `url` accepts params/query plus the same address options. The route transport is
chosen by the declaration; callers do not branch for HTTP, socket, or queue.

`ensureEntrypointFailureService(context)` returns the context-local failure plugin host. Register
an `onFailure` plugin there to observe a rejected remote `invoke`/`call`, show a toast, or collect
diagnostics. Plugins run after the transport fails and the original error is still rethrown to
the caller. This is the opt-in seam for application-wide failure UI; keep the transport independent
of the chosen toast library.