@atolljs/islands 0.1.12 → 0.1.13

package/dist/app.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Component-reference app handles — `islandApp(name, app)` stamps an app
+ * (React component or `{ imperative }` def) with its registry name so the
+ * shell can mount by reference: `<Island app={ChartsApp} props={…}/>` gets
+ * prop inference from the component's own signature while the wire still
+ * carries a string instance key.
+ *
+ * Why a stamp instead of `Component.name`: bundlers mangle function names
+ * in production builds, so `ChartsApp` → 'charts' can't be derived reliably.
+ * The stamp is a plain data property — stable through minification.
+ */
+import type { IslandContract } from './contract.js';
+/**
+ * Stamp an app with its registry name. The stamped value IS the app — use
+ * it directly as the `apps` map value in `definePolyWorker` and as the
+ * `app` prop of `<Island/>`.
+ *
+ * ```ts
+ * // worker/apps.tsx
+ * export const ChartsApp = islandApp('charts', function ChartsApp(props: ChartsProps) { ... });
+ * export const mapApp = islandApp('map', { imperative: buildMap });
+ * // worker entry: apps: { charts: ChartsApp, map: mapApp }
+ * // shell:        <Island app={ChartsApp} props={{ width: 520 }} />
+ * ```
+ */
+export declare const islandApp: <A>(name: string, app: A) => A & {
+    readonly islandAppName: string;
+};
+/**
+ * Resolve a mountable app reference to its wire name:
+ * string → itself; stamped app → its `islandAppName`; otherwise falls back
+ * to displayName/function name (dev-mode convenience — minification may
+ * strip it, which is what the stamp exists for). `undefined` when nothing
+ * derivable remains.
+ */
+export declare const islandAppNameOf: (app: unknown) => string | undefined;
+/**
+ * The props an app reference infers: a React component's own props, an
+ * imperative def's props parameter, `Record<string, unknown>` for plain
+ * string names (the un-typed mount path). Interfaces without index
+ * signatures still infer here — serialization happens at mount.
+ */
+export type IslandAppProps<A> = A extends IslandContract<infer P, infer _E> ? P : A extends {
+    imperative: (doc: never, props: infer P) => void;
+} ? P : A extends (props: infer P) => unknown ? P : Record<string, unknown>;
+/**
+ * The structural shape of a mountable app — `never` params so ANY component,
+ * imperative def, or framework-adapter output (`{ mount }` — what
+ * `reactIslandApp`/`vueIslandApp`/`reactIsland` produce) is assignable.
+ * Kept worker-free: importing the real `IslandApp` union from
+ * `worker/defineWorkers` would drag worker code into shell bundles.
+ */
+export type IslandAppLike = ((props: never) => unknown) | {
+    imperative: (doc: never, props: never) => void;
+} | {
+    mount: (ctx: never) => unknown;
+} | IslandContract;

package/dist/callbackProps.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Callback-prop marshalling — props cross postMessage as plain data, so a
+ * function prop can't travel as-is. `callbackProp(fn)` marks a shell-side
+ * function; mount/updateProps marshal markers into `{ __cb: id }` handles
+ * (registered in the island's callback table); the worker deserializes
+ * them into callables that push an `emit` op back on a reserved name, and
+ * the driver dispatches those emits to the table instead of `onEvent`.
+ *
+ * Fire-and-forget by design: the worker can't await a shell function — the
+ * call returns `undefined` in-worker. A callback invoked from a dispatched
+ * event lands on the shell in the same postMessage round trip; invoked from
+ * a timer/continuation it still routes correctly (instance captured at mount).
+ */
+/** Reserved emit-op name — payload `{ id, args }`, consumed by the driver. */
+export declare const CALLBACK_EVENT = "__island_cb__";
+/**
+ * Mark a shell function so it can travel as a prop: `mountIsland({ props:
+ * { onSave: callbackProp(fn) } })`. In the worker the prop arrives as a
+ * callable — invoking it fires `fn(...args)` on the shell asynchronously.
+ * The callable returns `undefined` (fire-and-forget — no await channel).
+ */
+export declare function callbackProp<Args extends unknown[]>(fn: (...args: Args) => void): (...args: Args) => void;
+/** True for a `callbackProp(fn)` marker — devtools previews show it as '[fn]'. */
+export declare const isCallbackMarker: (v: unknown) => boolean;
+/**
+ * Shell side: walk props replacing `callbackProp` markers with `{ __cb: id }`
+ * wire handles — `register` assigns each function a table id. Runs before
+ * the structured-clone preflight (markers hold a function — uncloneable).
+ */
+export declare function marshalCallbackProps(value: unknown, register: (fn: (...args: unknown[]) => void) => number): unknown;
+/**
+ * Worker side: walk received props replacing `{ __cb: id }` handles with
+ * callables — `make` wraps an id into the emit-backed caller.
+ */
+export declare function unmarshalCallbackProps(value: unknown, make: (id: number) => (...args: unknown[]) => void): unknown;