@client-compose/client 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Client Compose Authors
+
+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,52 @@
-# Temporary Holding Version
+# @client-compose/client
 
-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.
+Framework-agnostic client for [Client Compose](https://github.com/client-compose/client-compose):
+a protocol for server-composed screens made of client-owned islands.
+
+Tier: **core** · Protocol: **v0** · Any JS runtime with `fetch` (browsers, React Native, Node 20+)
+
+```sh
+npm install @client-compose/client
+```
+
+> Using React or React Native? Use [`@client-compose/react`](https://www.npmjs.com/package/@client-compose/react),
+> which builds on this package.
+
+## Usage
+
+`IslandRegistry<R>` maps island types and versions to renderers. `R` is whatever your UI renders
+(a DOM node, a string of HTML, a framework element), so this core works with any UI layer.
+
+```ts
+import { buildRequest, fetchScreen, IslandRegistry, plan } from "@client-compose/client";
+import { ProfileHeaderV2 } from "./islands.generated"; // from @client-compose/codegen
+
+const registry = new IslandRegistry<HTMLElement>()
+  .register(ProfileHeaderV2, (props) => renderProfileHeader(props));
+
+const request = buildRequest(registry, "profile", { platform: "web", appVersion: "1.4.0" }, { userId });
+const response = await fetchScreen("https://api.example.com/compose", request, {
+  headers: { Authorization: `Bearer ${token}` },
+});
+
+const islands = plan(registry, response, {
+  onSkipped: (entry, reason) => console.warn("skipped island", entry.key, reason),
+});
+container.replaceChildren(...islands.map((island) => island.render()));
+```
+
+- **`buildRequest`** sends the island types and versions this client can render, so the composer
+  never returns one it can't.
+- **`plan`** returns renderable islands in order. Errored islands are omitted unless you pass
+  `onError`; islands with an unknown type, version or status are skipped and reported.
+- **`fetchScreen`** throws `ScreenFetchError` (with `status` and `body`) for non-2xx responses, and
+  accepts a custom `fetch` as its fourth argument.
+
+Props aren't validated at runtime; generate types with
+[`@client-compose/codegen`](https://www.npmjs.com/package/@client-compose/codegen) to keep them in
+sync with the composer.
+
+## Links
+
+- [Protocol spec](https://github.com/client-compose/client-compose/blob/main/spec/PROTOCOL.md)
+- [Examples](https://github.com/client-compose/client-compose/tree/main/examples/profile)

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { type Capabilities, type ClientContext, type IslandDescriptor, type IslandEntry, type ScreenRequest, type ScreenResponse } from "@client-compose/protocol";
+type OkEntry<P = any> = IslandEntry<P> & {
+    status: "ok";
+};
+type ErrorEntry = IslandEntry & {
+    status: "error";
+};
+export type IslandRenderer<R, P = any> = (props: P, entry: OkEntry<P>) => R;
+export declare class IslandRegistry<R> {
+    private renderers;
+    /** Register a renderer for a generated island descriptor: `register(ProfileHeaderV2, (props) => …)`. */
+    register<P>(island: IslandDescriptor<P>, render: IslandRenderer<R, P>): this;
+    register<P>(type: string, version: number, render: IslandRenderer<R, P>): this;
+    capabilities(): Capabilities;
+    get(type: string, version: number): IslandRenderer<R> | undefined;
+}
+export declare function buildRequest(registry: IslandRegistry<unknown>, screen: string, client: ClientContext, params?: Record<string, string>): ScreenRequest;
+export interface PlannedIsland<R> {
+    key: string;
+    render: () => R;
+}
+export type SkipReason = "unknown_island" | "unknown_status";
+export interface PlanOptions<R> {
+    /** Render something for errored islands. Default: omit them (spec §4.3). */
+    onError?: (entry: ErrorEntry) => R | undefined;
+    /** Called for islands the client can't render (spec §4.4). Useful for telemetry. */
+    onSkipped?: (entry: IslandEntry, reason: SkipReason) => void;
+}
+/** Turn a response into an ordered list of renderable islands. */
+export declare function plan<R>(registry: IslandRegistry<R>, response: ScreenResponse, options?: PlanOptions<R>): PlannedIsland<R>[];
+export declare class ScreenFetchError extends Error {
+    readonly status: number;
+    readonly body: string;
+    /** The protocol error code from the response body (e.g. "not_found"), if there was one. */
+    readonly code: string | undefined;
+    constructor(status: number, body: string);
+}
+export declare function fetchScreen(baseUrl: string, request: ScreenRequest, init?: RequestInit, fetchImpl?: typeof fetch): Promise<ScreenResponse>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAC;AAElC,KAAK,OAAO,CAAC,CAAC,GAAG,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,CAAC;AAC1D,KAAK,UAAU,GAAG,WAAW,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAEpD,MAAM,MAAM,cAAc,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAE5E,qBAAa,cAAc,CAAC,CAAC;IAC3B,OAAO,CAAC,SAAS,CAAqD;IAEtE,wGAAwG;IACxG,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IAC5E,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IAe9E,YAAY,IAAI,YAAY;IAM5B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,SAAS;CAGlE;AAED,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,EACjC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,aAAa,EACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,aAAa,CAEf;AAED,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC,CAAC;CACjB;AAED,MAAM,MAAM,UAAU,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAE7D,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,CAAC,GAAG,SAAS,CAAC;IAC/C,oFAAoF;IACpF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;CAC9D;AAED,kEAAkE;AAClE,wBAAgB,IAAI,CAAC,CAAC,EACpB,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,EAC3B,QAAQ,EAAE,cAAc,EACxB,OAAO,GAAE,WAAW,CAAC,CAAC,CAAM,GAC3B,aAAa,CAAC,CAAC,CAAC,EAAE,CAoBpB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEtB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAMzC;AAWD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,WAAgB,EACtB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,cAAc,CAAC,CASzB"}

package/dist/index.js

@@ -0,0 +1,80 @@
+// Framework-agnostic client core for JS/TS frontends (web, React Native, etc).
+// `R` is whatever your UI layer renders: a React element, a DOM node, a string...
+import { PROTOCOL_VERSION, } from "@client-compose/protocol";
+export class IslandRegistry {
+    renderers = new Map();
+    register(islandOrType, versionOrRender, maybeRender) {
+        const [type, version, render] = typeof islandOrType === "string"
+            ? [islandOrType, versionOrRender, maybeRender]
+            : [islandOrType.type, islandOrType.version, versionOrRender];
+        if (!this.renderers.has(type))
+            this.renderers.set(type, new Map());
+        this.renderers.get(type).set(version, render);
+        return this;
+    }
+    capabilities() {
+        return Object.fromEntries([...this.renderers].map(([type, versions]) => [type, [...versions.keys()].sort((a, b) => a - b)]));
+    }
+    get(type, version) {
+        return this.renderers.get(type)?.get(version);
+    }
+}
+export function buildRequest(registry, screen, client, params) {
+    return { protocol: PROTOCOL_VERSION, screen, params, client, islands: registry.capabilities() };
+}
+/** Turn a response into an ordered list of renderable islands. */
+export function plan(registry, response, options = {}) {
+    const out = [];
+    for (const entry of response.islands) {
+        if (entry.status === "error") {
+            const fallback = options.onError?.(entry);
+            if (fallback !== undefined)
+                out.push({ key: entry.key, render: () => fallback });
+            continue;
+        }
+        if (entry.status !== "ok") {
+            options.onSkipped?.(entry, "unknown_status");
+            continue;
+        }
+        const renderer = registry.get(entry.type, entry.version);
+        if (!renderer) {
+            options.onSkipped?.(entry, "unknown_island");
+            continue;
+        }
+        out.push({ key: entry.key, render: () => renderer(entry.props, entry) });
+    }
+    return out;
+}
+export class ScreenFetchError extends Error {
+    status;
+    body;
+    /** The protocol error code from the response body (e.g. "not_found"), if there was one. */
+    code;
+    constructor(status, body) {
+        super(`Screen request failed with status ${status}`);
+        this.status = status;
+        this.body = body;
+        this.code = errorCode(body);
+    }
+}
+function errorCode(body) {
+    try {
+        const code = JSON.parse(body).error?.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function fetchScreen(baseUrl, request, init = {}, fetchImpl = fetch) {
+    const res = await fetchImpl(`${baseUrl}/screens/${encodeURIComponent(request.screen)}`, {
+        ...init,
+        method: "POST",
+        headers: { "content-type": "application/json", ...init.headers },
+        body: JSON.stringify(request),
+    });
+    if (!res.ok)
+        throw new ScreenFetchError(res.status, await res.text());
+    return (await res.json());
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@client-compose/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Framework-agnostic Client Compose client: island registry, screen requests and render planning.",
+  "keywords": [
+    "client-compose",
+    "server-driven-ui",
+    "backend-for-frontend",
+    "islands",
+    "client"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/client-compose/client-compose.git",
+    "directory": "clients/typescript/core"
+  },
+  "homepage": "https://github.com/client-compose/client-compose/tree/main/clients/typescript/core#readme",
+  "bugs": {
+    "url": "https://github.com/client-compose/client-compose/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@client-compose/protocol": "0.2.0"
+  },
+  "devDependencies": {
+    "@client-compose/conformance": "0.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
 }

package/src/index.ts

@@ -0,0 +1,137 @@
+// Framework-agnostic client core for JS/TS frontends (web, React Native, etc).
+// `R` is whatever your UI layer renders: a React element, a DOM node, a string...
+
+import {
+  PROTOCOL_VERSION,
+  type Capabilities,
+  type ClientContext,
+  type IslandDescriptor,
+  type IslandEntry,
+  type ScreenRequest,
+  type ScreenResponse,
+} from "@client-compose/protocol";
+
+type OkEntry<P = any> = IslandEntry<P> & { status: "ok" };
+type ErrorEntry = IslandEntry & { status: "error" };
+
+export type IslandRenderer<R, P = any> = (props: P, entry: OkEntry<P>) => R;
+
+export class IslandRegistry<R> {
+  private renderers = new Map<string, Map<number, IslandRenderer<R>>>();
+
+  /** Register a renderer for a generated island descriptor: `register(ProfileHeaderV2, (props) => …)`. */
+  register<P>(island: IslandDescriptor<P>, render: IslandRenderer<R, P>): this;
+  register<P>(type: string, version: number, render: IslandRenderer<R, P>): this;
+  register<P>(
+    islandOrType: IslandDescriptor<P> | string,
+    versionOrRender: number | IslandRenderer<R, P>,
+    maybeRender?: IslandRenderer<R, P>,
+  ): this {
+    const [type, version, render] =
+      typeof islandOrType === "string"
+        ? [islandOrType, versionOrRender as number, maybeRender!]
+        : [islandOrType.type, islandOrType.version, versionOrRender as IslandRenderer<R, P>];
+    if (!this.renderers.has(type)) this.renderers.set(type, new Map());
+    this.renderers.get(type)!.set(version, render);
+    return this;
+  }
+
+  capabilities(): Capabilities {
+    return Object.fromEntries(
+      [...this.renderers].map(([type, versions]) => [type, [...versions.keys()].sort((a, b) => a - b)]),
+    );
+  }
+
+  get(type: string, version: number): IslandRenderer<R> | undefined {
+    return this.renderers.get(type)?.get(version);
+  }
+}
+
+export function buildRequest(
+  registry: IslandRegistry<unknown>,
+  screen: string,
+  client: ClientContext,
+  params?: Record<string, string>,
+): ScreenRequest {
+  return { protocol: PROTOCOL_VERSION, screen, params, client, islands: registry.capabilities() };
+}
+
+export interface PlannedIsland<R> {
+  key: string;
+  render: () => R;
+}
+
+export type SkipReason = "unknown_island" | "unknown_status";
+
+export interface PlanOptions<R> {
+  /** Render something for errored islands. Default: omit them (spec §4.3). */
+  onError?: (entry: ErrorEntry) => R | undefined;
+  /** Called for islands the client can't render (spec §4.4). Useful for telemetry. */
+  onSkipped?: (entry: IslandEntry, reason: SkipReason) => void;
+}
+
+/** Turn a response into an ordered list of renderable islands. */
+export function plan<R>(
+  registry: IslandRegistry<R>,
+  response: ScreenResponse,
+  options: PlanOptions<R> = {},
+): PlannedIsland<R>[] {
+  const out: PlannedIsland<R>[] = [];
+  for (const entry of response.islands) {
+    if (entry.status === "error") {
+      const fallback = options.onError?.(entry);
+      if (fallback !== undefined) out.push({ key: entry.key, render: () => fallback });
+      continue;
+    }
+    if (entry.status !== "ok") {
+      options.onSkipped?.(entry, "unknown_status");
+      continue;
+    }
+    const renderer = registry.get(entry.type, entry.version);
+    if (!renderer) {
+      options.onSkipped?.(entry, "unknown_island");
+      continue;
+    }
+    out.push({ key: entry.key, render: () => renderer(entry.props, entry) });
+  }
+  return out;
+}
+
+export class ScreenFetchError extends Error {
+  readonly status: number;
+  readonly body: string;
+  /** The protocol error code from the response body (e.g. "not_found"), if there was one. */
+  readonly code: string | undefined;
+
+  constructor(status: number, body: string) {
+    super(`Screen request failed with status ${status}`);
+    this.status = status;
+    this.body = body;
+    this.code = errorCode(body);
+  }
+}
+
+function errorCode(body: string): string | undefined {
+  try {
+    const code = (JSON.parse(body) as { error?: { code?: unknown } }).error?.code;
+    return typeof code === "string" ? code : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function fetchScreen(
+  baseUrl: string,
+  request: ScreenRequest,
+  init: RequestInit = {},
+  fetchImpl: typeof fetch = fetch,
+): Promise<ScreenResponse> {
+  const res = await fetchImpl(`${baseUrl}/screens/${encodeURIComponent(request.screen)}`, {
+    ...init,
+    method: "POST",
+    headers: { "content-type": "application/json", ...init.headers },
+    body: JSON.stringify(request),
+  });
+  if (!res.ok) throw new ScreenFetchError(res.status, await res.text());
+  return (await res.json()) as ScreenResponse;
+}