@atolljs/react-island 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolljs/react-island",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "React shell components for atoll-islands islands — <Island/>, islandComponent, lazyIsland",
   "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
   "type": "module",
@@ -16,8 +16,8 @@
     "registry": "https://registry.npmjs.org"
   },
   "peerDependencies": {
-    "@atolljs/core": "0.1.5",
-    "@atolljs/islands": "0.1.5",
+    "@atolljs/core": "0.1.7",
+    "@atolljs/islands": "0.1.7",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "react-reconciler": "^0.34.0"

package/src/index.tsx

@@ -47,6 +47,7 @@ import { createPortal } from 'react-dom';
 import type { HTMLAttributes, ReactElement, ReactNode, Ref } from 'react';
 import {
   connectIslandWorker,
+  contractWorkerOf,
   islandAppNameOf,
   mountIsland,
 } from '@atolljs/islands';
@@ -54,6 +55,9 @@ import type {
   IslandAppLike,
   IslandAppProps,
   IslandClient,
+  IslandContract,
+  IslandContractEventHandler,
+  IslandContractProps,
   IslandHandle,
   IslandWorkerOptions,
   Mode,
@@ -183,9 +187,14 @@ export function Island<A = string>({
       return;
     }
 
+    // A contract `app` can carry its own worker factory — the contract
+    // module is then the whole connection, call sites pass no worker.
+    const resolvedWorker = worker ?? contractWorkerOf(app);
     const client =
       clientProp ??
-      (worker !== undefined ? connectIslandWorker({ worker, ...workerOptions }) : undefined);
+      (resolvedWorker !== undefined
+        ? connectIslandWorker({ worker: resolvedWorker, ...workerOptions })
+        : undefined);
     if (client === undefined) {
       report(new Error('<Island> requires either `worker` or `client`'));
       return;
@@ -423,11 +432,18 @@ function ProxyIsland({
  * contract-module shape `{ app: A, worker? }`, passes bare A through.
  */
 export type LazyResolvedApp<T extends Promise<unknown>> =
-  Awaited<T> extends { app: infer A }
-    ? A
-    : Awaited<T> extends { default: infer D }
-      ? D
-      : Awaited<T>;
+  // A contract object IS a lazy module (`{ app, worker? }` + brand) — match
+  // it before `{ app: infer A }` so props infer `P`, not `app`'s string.
+  // The never guard keeps a `Promise.reject` loader on the untyped path.
+  [Awaited<T>] extends [never]
+    ? string
+    : Awaited<T> extends { readonly islandContract: true }
+      ? Awaited<T>
+      : Awaited<T> extends { app: infer A }
+        ? A
+        : Awaited<T> extends { default: infer D }
+          ? D
+          : Awaited<T>;
 
 /**
  * `islandComponent<P>('charts')` — a proxy component for a worker app that
@@ -441,6 +457,21 @@ export type LazyResolvedApp<T extends Promise<unknown>> =
  * <TableIsland worker={renderWorker} filter={filter} desc={desc} />
  * ```
  */
+/**
+ * `islandComponent(checkoutContract)` — the cross-framework facade: a
+ * worker app described by `defineIslandContract` mounts by the contract's
+ * `app` key, props come from its schema, and `onEvent` narrows to the
+ * declared event vocabulary. The shell imports the CONTRACT module only —
+ * never the component or its framework.
+ */
+export function islandComponent<C extends IslandContract>(
+  app: C,
+): (
+  props: IslandContractProps<C> &
+    Omit<IslandShellProps, 'onEvent'> & {
+      onEvent?: IslandContractEventHandler<C>;
+    },
+) => ReactElement;
 export function islandComponent<P extends object = Record<string, unknown>>(
   app?: string,
 ): (props: P & IslandShellProps) => ReactElement;

package/src/worker.ts

@@ -35,10 +35,12 @@ import {
   definePolyWorker,
   islandApp,
   islandAppNameOf,
+  withContract,
 } from '@atolljs/islands/worker';
 import type {
   DoorbellSpec,
   ImperativeIslandApp,
+  IslandContract,
   IslandWorkerMethods,
   RenderContext,
   RenderedHandle,
@@ -65,7 +67,10 @@ type AnyComponent = ComponentType<Record<string, unknown>>;
  * the wrap, so registry warn-checks and `defineMonoWorker` name resolution
  * still see the shell-facing name.
  */
-export function reactIslandApp(App: AnyComponent): RenderedIslandApp {
+export function reactIslandApp(
+  App: AnyComponent,
+  contract?: IslandContract,
+): RenderedIslandApp {
   const app: RenderedIslandApp = {
     mount({ instance, props }: RenderContext): RenderedHandle {
       const react = createReactInstance(instance);
@@ -82,7 +87,9 @@ export function reactIslandApp(App: AnyComponent): RenderedIslandApp {
   };
   const stamp = islandAppNameOf(App);
   if (stamp !== undefined) (app as { islandAppName?: string }).islandAppName = stamp;
-  return app;
+  // Contract stamp — the engine validates mount/updateProps props and
+  // declared emit payloads against it.
+  return contract !== undefined ? withContract(contract, app) : app;
 }
 
 /** Stamp + wrap in one step — `reactIsland('charts', ChartsApp)` yields the
@@ -90,8 +97,9 @@ export function reactIslandApp(App: AnyComponent): RenderedIslandApp {
 export const reactIsland = (
   name: string,
   App: AnyComponent,
+  contract?: IslandContract,
 ): RenderedIslandApp & { readonly islandAppName: string } =>
-  islandApp(name, reactIslandApp(App));
+  islandApp(name, reactIslandApp(App, contract));
 
 export interface ReactPolyWorkerRegistry {
   /**
@@ -131,9 +139,11 @@ export function defineReactPolyWorker(
  */
 export function defineReactMonoWorker(
   app: AnyComponent | ImperativeIslandApp | RenderedIslandApp,
-  options?: { sharedMemory?: SharedMemory<DoorbellSpec> },
+  options?: { sharedMemory?: SharedMemory<DoorbellSpec>; contract?: IslandContract },
 ): WorkerDefinition<DoorbellSpec, IslandWorkerMethods> {
-  return typeof app === 'function'
-    ? defineMonoWorker(reactIslandApp(app), options)
-    : defineMonoWorker(app, options);
+  const resolved = typeof app === 'function' ? reactIslandApp(app) : app;
+  return defineMonoWorker(
+    options?.contract !== undefined ? withContract(options.contract, resolved) : resolved,
+    options,
+  );
 }