@requence/service 0.8.2-edge.1154 → 0.8.2-edge.1156

package/build/types/service/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAA;AAE3E,OAA6B,EAC3B,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EAEpB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAC9D,OAAO,EACL,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,mBAAmB,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAE1B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,cAAc,GACf,MAAM,2BAA2B,CAAA;AAGlC,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACtE,MAAM,MAAM,UAAU,CACpB,CAAC,SAAS,MAAM,eAAe,CAAC,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,IACrD,aAAa,CAAC,CAAC,CAAC,CAAA;AAEpB,UAAU,cAAc,CAAC,CAAC,SAAS,MAAM;IACvC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,CAAC,CAAA;IACV;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,iBAAiB,CAAC,EAAE,4BAA4B,CAAC,mBAAmB,CAAC,CAAA;IACrE,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,CAAA;IAGvB,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,uBAAuB,CAAA;CAClD;AAwCD,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,eAAe,CAAC,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EACvD,OAAO,EAAE,CAAC,EAAE,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA;AAC/D,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,eAAe,CAAC,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EACvD,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAA;AAE3E,OAA6B,EAC3B,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EAEpB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAC9D,OAAO,EACL,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,mBAAmB,CAAA;AAC1B,cAAc,aAAa,CAAA;AAK3B,YAAY,EACV,WAAW,EACX,aAAa,EACb,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,EACZ,cAAc,EACd,SAAS,GACV,MAAM,gBAAgB,CAAA;AACvB,cAAc,SAAS,CAAA;AACvB,cAAc,YAAY,CAAA;AAE1B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,cAAc,GACf,MAAM,2BAA2B,CAAA;AAGlC,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACtE,MAAM,MAAM,UAAU,CACpB,CAAC,SAAS,MAAM,eAAe,CAAC,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,IACrD,aAAa,CAAC,CAAC,CAAC,CAAA;AAEpB,UAAU,cAAc,CAAC,CAAC,SAAS,MAAM;IACvC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,CAAC,CAAA;IACV;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,iBAAiB,CAAC,EAAE,4BAA4B,CAAC,mBAAmB,CAAC,CAAA;IACrE,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,CAAA;IAGvB,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,uBAAuB,CAAA;CAClD;AA4CD,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,eAAe,CAAC,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EACvD,OAAO,EAAE,CAAC,EAAE,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA;AAC/D,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,eAAe,CAAC,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EACvD,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA"}

package/build/types/service/src/surfaceHandler.d.ts

@@ -0,0 +1,36 @@
+import type { SurfaceHandlerObject } from '../../helpers/src/index.js';
+import type { ValueHandler } from '@requence/transformer';
+/** What a render's egress needs to turn one function prop into a reference. */
+export interface SurfaceHandlerEgressContext {
+    /**
+     * Register a function found in a render payload and return its reference.
+     *
+     * Takes the value's **path in the payload**, which is the whole of what
+     * decides the reference's lifetime: a function under `defaults` was written at
+     * module scope and is durable, one under `props` was written at the render
+     * call and belongs to the publishing connection (#103). Nothing else about
+     * the function can tell the two apart, and the walk is the only place the
+     * position is known.
+     *
+     * Absent ⇒ this boundary is not a render boundary and a function on it is the
+     * ordinary callback case; see `transformer.ts`.
+     */
+    onSurfaceHandler(handler: (...args: unknown[]) => void, path: ReadonlyArray<string | number>): SurfaceHandlerObject;
+}
+/**
+ * The `RequenceHandler` tag's egress half, composed onto the **render**
+ * transformer only (`transformer.ts`).
+ *
+ * It claims functions exactly as the callback handler does, which is why the two
+ * live on different transformer instances rather than one: a function in a render
+ * payload is a surface handler, a function anywhere else in a service's output is
+ * a peer callback, and `canHandle` cannot see the difference.
+ *
+ * There is no ingress. A handler reference travels service → operator →
+ * ui/backend → browser and is never transformed back into a function by anyone:
+ * the browser holds a props path, and the invocation comes back as its own
+ * message. A reference reaching an inbound walk is therefore a routing bug, and
+ * says so.
+ */
+export declare function createSurfaceHandlerValueHandler(): ValueHandler<(...args: unknown[]) => void, SurfaceHandlerObject, SurfaceHandlerEgressContext>;
+//# sourceMappingURL=surfaceHandler.d.ts.map

package/build/types/service/src/surfaceHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceHandler.d.ts","sourceRoot":"","sources":["../../../../src/surfaceHandler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAE7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEzD,+EAA+E;AAC/E,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;;;OAYG;IACH,gBAAgB,CACd,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,EACrC,IAAI,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,GACnC,oBAAoB,CAAA;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gCAAgC,IAAI,YAAY,CAC9D,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,EAC5B,oBAAoB,EACpB,2BAA2B,CAC5B,CAmBA"}

package/build/types/service/src/surfaceUi.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Type declarations for `@requence/surface-ui` — the **primitives facade** of the
+ * surface host's shared runtime (`knowledge/service-ui-surfaces.md` D14), plus the
+ * React mount helper that ships beside them (#113).
+ *
+ * Declarations only: nothing here exists at run time in a service process. A
+ * component leaves `@requence/surface-ui` external in its own bundle, and the
+ * surface host's import map binds the specifier to its runtime build inside the
+ * frame. The implementation these mirror lives in
+ * `ui/frontend/surface-runtime/ui.tsx`.
+ *
+ * **This import is the opt-in, and it is where the price is paid** (D12/D13).
+ * There is no flag to set and nothing to declare at `createUI`: the host installs
+ * the import map for every surface, so marking `react`, `react-dom/client`,
+ * `react/jsx-runtime` and this specifier **external** is the whole of it. What it
+ * buys is a much smaller bundle and the host app's own look; what it costs has no
+ * escape hatch — there is exactly **one** runtime version, *current*. Nothing to
+ * pin, no old builds retained, so a host upgrade (a React major, a refactored
+ * primitive) can break a published component, which then shows the standard error
+ * state on its node. A bundle that ships its own framework imports none of these
+ * and is immune; `context.debug` stays the diagnostic underneath either way.
+ *
+ * They are shipped by the SDK so a component author gets a typed, JSX-checked
+ * facade from the one package they already depend on. The specifier itself is
+ * declared where it is used, because only the component's own build knows it is
+ * external:
+ *
+ * ```ts
+ * // surface-ui.d.ts, next to the component
+ * declare module '@requence/surface-ui' {
+ *   export * from '@requence/service/surface-ui'
+ * }
+ * ```
+ *
+ * Like the facade itself, these are explicitly **best-effort** (D13/D14): there
+ * is one runtime version, *current*, so they describe what the host renders
+ * today and carry no compatibility guarantee. Hand-mirrored, therefore able to
+ * drift from the facade — additions there stay non-breaking, and a component
+ * that breaks against a host upgrade shows the standard error state on its node.
+ */
+import type { Mount, SurfaceState } from '../../helpers/src/index.js';
+import type { CSSProperties, ComponentProps, ReactElement, ReactNode, SelectHTMLAttributes } from 'react';
+/**
+ * Turns a React component into the `mount` the surface frame calls, absorbing the
+ * four steps every component repeated — create the root, hold the state,
+ * subscribe to `onUpdate`, unmount on teardown:
+ *
+ * ```tsx
+ * import { Button, createSurface } from '@requence/surface-ui'
+ *
+ * import type { PropsOf } from '@requence/service'
+ * import type { buttonUI } from './button.ts'
+ *
+ * export default createSurface<PropsOf<typeof buttonUI>>(({ props, canInvoke }) => (
+ *   <Button disabled={!canInvoke} onClick={() => props.onClick()}>
+ *     {props.label}
+ *   </Button>
+ * ))
+ * ```
+ *
+ * The component receives the surface state as its own props, so `props`,
+ * `canInvoke` and `theme` are destructured directly. Anything nested reads the
+ * same state with {@link useSurface} rather than having it drilled down.
+ *
+ * It is a **facade** export, not an SDK one: the implementation is the host's, and
+ * a bundle that ships its own React writes the `mount` itself. `SurfaceState` and
+ * `Mount` come from `@requence/service`, which is where they are documented.
+ */
+export declare function createSurface<Props>(Component: (state: SurfaceState<Props>) => ReactNode): Mount<Props>;
+/**
+ * Reads the surface state anywhere inside a {@link createSurface} tree — the same
+ * object the top-level component receives as props, re-read on every update.
+ *
+ * ```tsx
+ * function SubmitRow() {
+ *   const { props, canInvoke } = useSurface<PropsOf<typeof askUI>>()
+ *
+ *   return <Button disabled={!canInvoke} onClick={() => props.onSubmit()}>Send</Button>
+ * }
+ * ```
+ *
+ * Throws outside such a tree. `Props` is your assertion, exactly as it is at
+ * `createSurface`: nothing on the wire declares a shape for a service's props.
+ */
+export declare function useSurface<Props>(): SurfaceState<Props>;
+/** The facade's spacing scale, in 4px steps. (`Space`, in the facade itself.) */
+export type SurfaceSpace = 0 | 1 | 2 | 3 | 4;
+export interface StackProps {
+    children?: ReactNode;
+    /** `column` (the default) or `row`. */
+    direction?: 'column' | 'row';
+    /** Gap between children, in 4px steps. */
+    space?: SurfaceSpace;
+    /** Padding, in 4px steps. */
+    padding?: SurfaceSpace;
+    align?: CSSProperties['alignItems'];
+    justify?: CSSProperties['justifyContent'];
+    wrap?: boolean;
+    grow?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/** The layout primitive: a flex column or row with a spacing scale. */
+export declare function Stack(props: StackProps): ReactElement;
+export interface TextProps {
+    children?: ReactNode;
+    variant?: 'body' | 'title' | 'muted' | 'code';
+    className?: string;
+    style?: CSSProperties;
+}
+/** The text primitive. `code` renders monospace and preserves whitespace. */
+export declare function Text(props: TextProps): ReactElement;
+export interface ButtonProps extends Omit<ComponentProps<'button'>, 'className'> {
+    severity?: 'danger';
+    small?: boolean;
+    className?: string;
+}
+export declare function Button(props: ButtonProps): ReactElement;
+export interface TextFieldProps extends Omit<ComponentProps<'input'>, 'className'> {
+    label?: ReactNode;
+    className?: string;
+}
+export declare function TextField(props: TextFieldProps): ReactElement;
+export interface SelectOption {
+    value: string;
+    label?: string;
+    disabled?: boolean;
+}
+export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'className' | 'children'> {
+    label?: ReactNode;
+    /** The choices. A plain array, so no child component vocabulary is needed. */
+    options: SelectOption[];
+    className?: string;
+}
+export declare function Select(props: SelectProps): ReactElement;
+export interface CheckboxProps extends Omit<ComponentProps<'input'>, 'className' | 'type'> {
+    label?: ReactNode;
+    className?: string;
+}
+export declare function Checkbox(props: CheckboxProps): ReactElement;
+//# sourceMappingURL=surfaceUi.d.ts.map

package/build/types/service/src/surfaceUi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceUi.d.ts","sourceRoot":"","sources":["../../../../src/surfaceUi.ts"],"names":[],"mappings":"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"}

package/build/types/service/src/transformer.d.ts

@@ -5,6 +5,20 @@
  * (`boundary.ts`) is the only place that builds those ctx objects.
  */
 export declare const transformer: import("@requence/transformer").Transformer<import("@requence/files").FileEgressContext & import("@requence/files").StreamEgressContext & import("@requence/callbacks").CallbackEgressContext & object & import("@requence/files").ClaimCheckEgressContext, import("@requence/callbacks").CallbackIngressContext & object>;
+/**
+ * The **render** payload's egress chain: the same byte references, with the
+ * callback handler swapped for the surface-handler one (#103).
+ *
+ * A second instance rather than a fifth handler on the first, because both
+ * claim every function and `canHandle` gets nothing to tell them apart. Which
+ * of the two is right is a property of the *payload*, not of the value: a
+ * function in a render is a handler prop the browser will press, a function
+ * anywhere else in a service's output is a callback a peer service will call.
+ * Choosing per boundary is the only place that distinction actually exists.
+ *
+ * Outbound-only in practice — nothing ever inbound-transforms a render.
+ */
+export declare const renderTransformer: import("@requence/transformer").Transformer<import("@requence/files").FileEgressContext & import("@requence/files").StreamEgressContext & import("./surfaceHandler.ts").SurfaceHandlerEgressContext & object & import("@requence/files").ClaimCheckEgressContext, object>;
 /**
  * Inbound chain for passthrough consumers (the logic runtime): claim-checks
  * still resolve — a state seed may arrive as a ClaimCheck reference — but

package/build/types/service/src/transformer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transformer.d.ts","sourceRoot":"","sources":["../../../../src/transformer.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,eAAO,MAAM,WAAW,4TAIiB,CAAA;AAqBzC;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,iHAID,CAAA"}
+{"version":3,"file":"transformer.d.ts","sourceRoot":"","sources":["../../../../src/transformer.ts"],"names":[],"mappings":"AAmBA;;;;;GAKG;AACH,eAAO,MAAM,WAAW,4TAEiB,CAAA;AAEzC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,2QAEW,CAAA;AAqBzC;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,iHAID,CAAA"}

package/build/types/service/src/ui.d.ts

@@ -0,0 +1,247 @@
+import type { WrappedRequenceCallback } from '../../helpers/src/index.js';
+/**
+ * A registered UI component: the built module's source plus its content hash.
+ * Opaque to the author at the value level — the only thing to do with it is pass
+ * it to `context.render(ui, props)`.
+ *
+ * `Props` is a phantom type parameter (never present at runtime) carrying the
+ * shape the service sends to this component. It is what makes `render(ui, props)`
+ * type-check against the service's own TypeScript, and what the component author
+ * reads back with {@link PropsOf} to type `mount`. Declare it once, at
+ * `createUI<Props>(url)`.
+ */
+export interface RequenceUI<Props = unknown> {
+    /**
+     * This component's **stable identity** — what a durable handler reference
+     * names (#103), and the one thing about a UI that a rebuild must not change.
+     *
+     * The content hash cannot serve: a rebuild changes it while the module-scope
+     * function in the defaults stays the same function, so a durable reference
+     * keyed on the hash would stop resolving the moment the component was rebuilt
+     * — and would never resolve at all in a process that started after the render.
+     * Defaults to the built module's **file name**, which survives both a rebuild
+     * and a restart; {@link CreateUIOptions.id} overrides it.
+     *
+     * Unique per process, enforced at registration: two components sharing an id
+     * would make a durable invocation ambiguous, and the failure would be a click
+     * reaching the wrong handler rather than anything visible.
+     */
+    readonly id: string;
+    /**
+     * The bundle's content hash. `readonly` to the author but not immutable: in
+     * service dev mode a rebuild of the watched file rewrites this and `source`
+     * in place (D10), which is what makes the next ordinary render carry the new
+     * bundle. Read it at use, never cache it.
+     */
+    readonly hash: string;
+    readonly source: string;
+    /**
+     * The props this component always has, as declared at `createUI` — restated on
+     * every render of it, so a service states once what does not change per
+     * message and a render carries only what differs.
+     *
+     * Sent as their own field of the render payload rather than merged into the
+     * render's props, because the receiver ranks them **lowest** (#102): a default
+     * is what a surface shows until some render says otherwise, and it never
+     * overrides what one already did. Merging them here would rank them highest
+     * instead, which is the one thing a default must not be.
+     *
+     * Absent rather than empty when none were declared, so the payload of a
+     * component without defaults is exactly what it always was.
+     *
+     * Deliberately **not** part of the hash: they are what the service sends, not
+     * what the browser loads, so two registrations of one built file still dedupe
+     * on the same bundle.
+     */
+    readonly defaults?: Partial<Props>;
+    /**
+     * Phantom carrier for the props type — optional and never assigned, so it
+     * adds no runtime surface. Only `render`/{@link PropsOf} read it at the type
+     * level.
+     */
+    readonly __props?: Props;
+}
+/**
+ * What every invokable prop carries in the component, beside being callable.
+ *
+ * `reachable` is the answer to "would pressing this do anything", **per prop**
+ * (#106) — because one surface can carry handlers of both lifetimes at once and
+ * a surface-wide flag necessarily lies about one of them:
+ *
+ * ```
+ * reachable(durable)    = the task is still running
+ * reachable(connection) = …and this surface's own connection is alive, with the
+ *                         reference belonging to its current render
+ * ```
+ *
+ * Read it *with* `ctx.canInvoke`, never instead of it: that one is permission,
+ * this one is whether there is anything at the other end. A control should be
+ * offered when both hold.
+ *
+ * Calling an unreachable handler **throws** (D32), naming the prop and the reason,
+ * and sends nothing. Catch it on `error.name === 'RequenceUnreachableHandlerError'`
+ * — the frame and your component share a realm but no module, so the name is the
+ * whole contract:
+ *
+ * ```js
+ * try {
+ *   props.onSubmit(answer)
+ * } catch (error) {
+ *   if (error.name === 'RequenceUnreachableHandlerError') showNotice(error.message)
+ *   else throw error
+ * }
+ * ```
+ *
+ * It used to warn instead, which could not be handled: a component had no signal
+ * that the click went nowhere, and `reachable` — readable before the call — races
+ * a flip that lands between the render and the press. Reading `reachable` to
+ * withhold the control is still right; the throw is what covers the race and the
+ * component that does not check.
+ *
+ * **The viewer is told either way.** The frame also reports the refusal to the
+ * canvas, which shows it beneath the surface in the same strip a permission or
+ * byte-cap refusal uses. So catching is about saying something *better* in your
+ * own words and your own layout — not about whether the failure is visible.
+ */
+export type HandlerReachability = {
+    readonly reachable: boolean;
+};
+/**
+ * An invokable prop as the component holds it: the function the service put in
+ * the props, plus {@link HandlerReachability}.
+ */
+export type RequenceHandler<Arg> = ((arg: Arg) => void) & HandlerReachability;
+/**
+ * How a single prop value looks to the component.
+ *
+ * Every function among the props is a **handler** the browser can invoke, so it
+ * arrives callable and carrying its own `reachable` flag. A callback sent by the
+ * service arrives rehydrated the same way (the browser is one more consumer of
+ * the same inbound transform a peer service uses), so the service-only
+ * `WrappedRequenceCallback` — its extra `.response()` — is reduced to what the
+ * component actually holds. Everything else passes through untouched, so branded
+ * values (`RequenceFile`, `RequenceStream`) and plain data keep their type
+ * exactly.
+ *
+ * The parameter list is preserved rather than collapsed to `RequenceHandler`'s
+ * single `Arg`, so a prop declared `onClose(): void` stays callable with no
+ * argument.
+ */
+type ComponentPropValue<V> = V extends WrappedRequenceCallback<infer Arg> ? RequenceHandler<Arg> : V extends (...args: infer Args) => unknown ? ((...args: Args) => void) & HandlerReachability : V;
+/**
+ * The props as the component receives them: the service-declared props with
+ * every top-level callback presented in its invokable form.
+ */
+export type ComponentProps<Props> = Props extends object ? {
+    [K in keyof Props]: ComponentPropValue<Props[K]>;
+} : Props;
+/**
+ * Extracts the component-facing props type from a `ui` handle, so a component
+ * author can type `mount` straight off the value they imported:
+ * `SurfaceContext<PropsOf<typeof ui>>`.
+ */
+export type PropsOf<U> = U extends RequenceUI<infer Props> ? ComponentProps<Props> : never;
+/**
+ * The props one render may supply: **any subset** of the component's props.
+ *
+ * A render is a patch, not a whole value (#102) — what the surface shows is the
+ * fold of the UI's defaults, everything previously rendered onto that surface,
+ * and this render — so omitting a prop is the normal case and cannot be an
+ * error. A handler that redraws one field is the reason the fold exists, and the
+ * clearest instance of it is a handler that *cannot* restate the rest: a durable
+ * one, running in a process that never saw the original render.
+ *
+ * The accepted cost, and it is a real one: TypeScript cannot see the accumulated
+ * state, so it can no longer tell a legitimate patch from a first render that
+ * forgot half its props. `PropsOf` — the component's side — stays whole and
+ * required, because the component genuinely does receive the folded object; it
+ * is the service's responsibility that the fold covers it.
+ */
+export type RenderProps<Props> = Partial<Props>;
+/**
+ * What a component is handed, re-exported from the one place all three readers
+ * share (#113): the SDK, the frame protocol and the shared runtime's
+ * `createSurface`. Declared in `@requence/helpers/utils/surfaceComponent.ts`,
+ * which is where the documentation lives — an author reads them from here.
+ */
+export type { Mount, SurfaceContext, SurfaceState, SurfaceTheme, } from '../../helpers/src/index.js';
+export interface CreateUIOptions {
+    /**
+     * Where the built module is — `new URL('./component.js', import.meta.url)`.
+     *
+     * A URL rather than a path because it is the one form that resolves against
+     * the *module that wrote it*: a relative path resolves against the process's
+     * working directory, so a service started from anywhere but its own package
+     * silently failed to find its own component.
+     */
+    url: URL;
+    /**
+     * Override this component's stable id ({@link RequenceUI.id}), which defaults
+     * to the built module's file name.
+     *
+     * Three reasons to set it, and the first two are about the default being a
+     * file name: two components in different directories that build to `index.js`
+     * collide, and renaming a built file silently retires every durable handler
+     * reference already sitting in a queue or stored on a surface. The third is
+     * registering **one** file twice — two handles with different defaults — which
+     * is a collision like any other.
+     *
+     * A collision throws at registration, at module scope, so it is a startup
+     * error rather than a click resolving against the wrong component's defaults.
+     */
+    id?: string;
+}
+/**
+ * Registers a UI component from an already-built ES module — one default export
+ * `mount(element, ctx)`. Requence never bundles: the author builds with their
+ * own toolchain, and this only reads the result and hashes it, which is what
+ * keeps the contract portable across SDKs.
+ *
+ * Called at module scope, next to `createService`, so an oversized bundle fails
+ * at registration rather than on the first render in production
+ * (knowledge/service-ui-surfaces.md D4).
+ *
+ * ```ts
+ * const askUI = createUI<{ question: string }>(
+ *   new URL('./ask.mount.js', import.meta.url), // or { url, id: 'ask' }
+ * )
+ * ```
+ *
+ * Nothing here declares how the bundle was built. A component may leave `react`,
+ * `react-dom/client`, `react/jsx-runtime` and `@requence/surface-ui` **external**
+ * and let the surface host's shared runtime resolve them — the import map is
+ * installed for every surface, so importing the facade is the whole opt-in, and
+ * its price is stated where that import is declared
+ * (`@requence/service/surface-ui`). A bundle that ships its own framework has no
+ * bare specifier left for the map to bind and is unaffected either way.
+ *
+ * Declare the props the service will send as the `Props` type argument: it is
+ * erased at runtime but flows to `render(ui, props)` and back to the component
+ * through {@link PropsOf}.
+ *
+ * `defaults` is any subset of `Props`, restated on every render of this
+ * component, so a service declares once what does not change per message:
+ *
+ * ```ts
+ * const panelUI = createUI<{ title: string; dense: boolean }>(
+ *   new URL('./panel.js', import.meta.url),
+ *   { dense: true },
+ * )
+ *
+ * context.render(panelUI, { title: 'Processing' }) // dense comes along
+ * ```
+ *
+ * They are the **weakest** layer of the surface's fold (#102): a render that
+ * names a defaulted prop overrides it, and it stays overridden for every later
+ * render that stays silent about it. A default answers "what does this surface
+ * show until something says otherwise", not "what does it show unless this
+ * render says otherwise".
+ *
+ * A function among them is a **durable** handler (D24): written at module scope, it
+ * closes over nothing one message owns, so any instance of the version can run it —
+ * including one started after the process that rendered has exited. That is the
+ * opposite of a function written inline at `context.render`, which dies with the
+ * message that published it. Where you write it is the whole decision.
+ */
+export declare function createUI<Props = unknown>(target: URL | CreateUIOptions, defaults?: Partial<Props>): RequenceUI<Props>;
+//# sourceMappingURL=ui.d.ts.map

package/build/types/service/src/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../../../src/ui.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAMhE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK,GAAG,OAAO;IACzC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;IAClC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC,GAAG,mBAAmB,CAAA;AAE7E;;;;;;;;;;;;;;;GAeG;AACH,KAAK,kBAAkB,CAAC,CAAC,IACvB,CAAC,SAAS,uBAAuB,CAAC,MAAM,GAAG,CAAC,GACxC,eAAe,CAAC,GAAG,CAAC,GACpB,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,OAAO,GACxC,CAAC,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC,GAAG,mBAAmB,GAC/C,CAAC,CAAA;AAET;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI,KAAK,SAAS,MAAM,GACpD;KAAG,CAAC,IAAI,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;CAAE,GACpD,KAAK,CAAA;AAET;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IACnB,CAAC,SAAS,UAAU,CAAC,MAAM,KAAK,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC,GAAG,KAAK,CAAA;AAEnE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,CAAA;AAE/C;;;;;GAKG;AACH,YAAY,EACV,KAAK,EACL,cAAc,EACd,YAAY,EACZ,YAAY,GACb,MAAM,mBAAmB,CAAA;AAE1B,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,GAAG,EAAE,GAAG,CAAA;IACR;;;;;;;;;;;;;OAaG;IACH,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,QAAQ,CAAC,KAAK,GAAG,OAAO,EACtC,MAAM,EAAE,GAAG,GAAG,eAAe,EAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,GACxB,UAAU,CAAC,KAAK,CAAC,CA0CnB"}

package/build/types/service/src/uiWatch.d.ts

@@ -0,0 +1,68 @@
+import type { RequenceUI } from './ui.ts';
+/**
+ * A component handle as the watcher holds it — the object `createUI` returned,
+ * with every field writable. Derived from {@link RequenceUI} rather than
+ * restated, so a field added there cannot go unwatched. The public type keeps
+ * them `readonly`: rewriting them is this module's job and nobody else's.
+ *
+ * "Writable" is wider than "rewritten": a rebuild only ever replaces `hash` and
+ * `source`, because they are the only fields that come out of the file. The rest
+ * (`id`, `defaults`) are mutable here purely because `createUI` builds
+ * the handle as this type — `id` in particular is the one field a rebuild must
+ * NOT touch (#103).
+ *
+ * (The import is type-only, so `ui.ts` importing this module back is not a
+ * runtime cycle.)
+ */
+export type MutableRequenceUI = {
+    -readonly [K in keyof Omit<RequenceUI, '__props'>]: RequenceUI[K];
+};
+export interface UIWatchListener {
+    /**
+     * A watched component's built file changed content. The handle already
+     * carries the new bytes; announcing the swap is the listener's job.
+     */
+    onRebuild: (ui: MutableRequenceUI) => void;
+    /**
+     * Something the author needs to hear about the watch itself. Reported rather
+     * than logged because this module is process-global and `silent` is a
+     * per-connection option — only the subscriber knows whether to print. Fanned
+     * out to every subscriber; in the normal case that is the one dev connection
+     * that turned the loop on.
+     */
+    onWarning: (message: string) => void;
+}
+/**
+ * Records a component built by `createUI`, so the dev loop can find it later.
+ *
+ * Unconditional, in every mode: `createUI` runs at module scope and cannot know
+ * whether the service it belongs to will connect with a dev token. Registration
+ * costs one object in a set and starts nothing — a watcher exists only once
+ * {@link watchUIRebuilds} is called, which only a dev-mode connection does.
+ */
+export declare function registerUI(ui: MutableRequenceUI, filePath: string): void;
+/**
+ * The UI a durable handler invocation names (#103), or `undefined` when this
+ * process has none under that id.
+ *
+ * Process-global, like the registry itself: a durable handler belongs to the
+ * *service version*, not to a connection, so whichever connection consumed the
+ * invocation resolves it against the same set of components the process
+ * registered at module scope.
+ */
+export declare function findUIById(id: string): MutableRequenceUI | undefined;
+/**
+ * Turns the dev loop on (D10): watch every registered component's built file
+ * and call `onRebuild` whenever one of them changes content.
+ *
+ * The handle itself is rewritten before the listener runs, so two things follow
+ * from one rebuild: every later render carries the new bundle (the render path
+ * reads the handle at call time), and the listener announces the swap for every
+ * surface already drawn (#108). Neither is a re-render — a rebuild changes which
+ * bytes the frame imports and nothing else — which is why the swap reaches a
+ * surface whose message has long since settled.
+ *
+ * Returns an unsubscribe. The last one out stops the watchers.
+ */
+export declare function watchUIRebuilds(listener: UIWatchListener): () => void;
+//# sourceMappingURL=uiWatch.d.ts.map

package/build/types/service/src/uiWatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uiWatch.d.ts","sourceRoot":"","sources":["../../../../src/uiWatch.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,CAAC,UAAU,CAAC,IAAI,MAAM,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;CAClE,CAAA;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,SAAS,EAAE,CAAC,EAAE,EAAE,iBAAiB,KAAK,IAAI,CAAA;IAC1C;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACrC;AAgCD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,QAsBjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,IAAI,CAmBrE"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@requence/service",
   "type": "module",
-  "version": "0.8.2-edge.1154",
+  "version": "0.8.2-edge.1156",
   "bin": {
     "requence-service": "build/cli.js"
   },
@@ -17,7 +17,6 @@
     "ajv": "^8.17.1",
     "amqp-connection-manager": "^4.1.14",
     "amqplib": "^0.10.8",
-    "chalk": "^5.6.2",
     "eventsource-client": "^1.2.0",
     "mime-types": "^3.0.1",
     "msgpackr": "^1.11.5",
@@ -28,15 +27,22 @@
     "@requence/callbacks": "workspace:*",
     "@requence/files": "workspace:*",
     "@requence/helpers": "workspace:*",
+    "@requence/logger": "workspace:*",
     "@requence/transformer": "workspace:*",
     "@requence/utils": "workspace:*",
     "@types/amqplib": "^0.10.7",
     "@types/bun": "^1.2.23",
+    "@types/react": "^19.2.17",
     "@types/yargs": "^17.0.33",
     "tsc-alias": "^1.8.16"
   },
   "exports": {
-    "default": "./build/index.js",
-    "types": "./build/types/service/src/index.d.ts"
+    ".": {
+      "types": "./build/types/service/src/index.d.ts",
+      "default": "./build/index.js"
+    },
+    "./surface-ui": {
+      "types": "./build/types/service/src/surfaceUi.d.ts"
+    }
   }
 }