@dreamboard-games/ui-sdk 0.0.41

package/dist/components/surfaces/internal/DefaultInteractionButton.d.ts

@@ -0,0 +1,71 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { ButtonVariant } from "../../../theme/derive.js";
+import type { InteractionHandle, InteractionParamsShape } from "../../../hooks/useInteractionHandle.js";
+import type { InteractionDescriptor } from "../../../types/plugin-state.js";
+export interface SubmittedActionConfig {
+    label?: ReactNode;
+    icon?: ReactNode;
+    variant?: ButtonVariant;
+}
+/**
+ * Default button used by every surface that does not get an explicit
+ * renderer override. The button reads its visual style from the active
+ * {@link useTheme()} via {@link buttonStyle}; styling is no longer
+ * configurable per call site. Authors who need a different look should
+ * either:
+ *
+ * 1. Mount a different theme via `<ThemeProvider>`, or
+ * 2. Provide a per-interaction renderer override on the surrounding
+ *    surface and draw their own button.
+ *
+ * The mapping from `descriptor.emphasis` to a {@link ButtonVariant}:
+ *
+ * - `"primary"`     → `primary`
+ * - `"destructive"` → `danger`
+ * - `"secondary"` (or unset) → `secondary`
+ *
+ * Override the mapping per call site with the `variant` prop when the
+ * descriptor's emphasis hint is wrong (e.g. an unavailable confirm that
+ * should still look prominent).
+ */
+export interface DefaultInteractionButtonProps<Params extends InteractionParamsShape = InteractionParamsShape> {
+    descriptor: InteractionDescriptor;
+    handle: InteractionHandle<Params>;
+    /** Override the variant inferred from `descriptor.emphasis`. */
+    variant?: ButtonVariant;
+    /** Content slot before the descriptor's icon and label. */
+    leading?: ReactNode;
+    /** Content slot after the descriptor's label. */
+    trailing?: ReactNode;
+    /**
+     * Prefer `descriptor.shortLabel` over `label`. Set by surfaces that
+     * group lots of interactions in a tight row.
+     */
+    compact?: boolean;
+    /**
+     * Button size token. Defaults to `md` (or `sm` when {@link compact}
+     * is set, preserving the historical sub-row geometry). Surfaces that
+     * resolve a salience tier — e.g. {@link PanelSurface} — pass
+     * `lg` for hero items so the visual weight matches the importance.
+     */
+    size?: "sm" | "md" | "lg";
+    /** Submit params forwarded to `handle.submit`. Defaults to `{}`. */
+    params?: Record<string, unknown>;
+    /** Copy and visual overrides once this interaction has been submitted. */
+    whenSubmitted?: SubmittedActionConfig;
+    /** Additional inline style merged after the resolved button style. */
+    style?: CSSProperties;
+    /** Start expanded when the descriptor needs form input. */
+    defaultFormOpen?: boolean;
+    /**
+     * Additional `data-*` attribute forwarded onto the `<button>` so
+     * surfaces can tag DOM nodes for tests / theming hooks (e.g.
+     * `data-panel-tier="hero"`).
+     */
+    "data-panel-tier"?: string;
+}
+/**
+ * @see DefaultInteractionButtonProps
+ */
+export declare function DefaultInteractionButton<Params extends InteractionParamsShape = InteractionParamsShape>({ descriptor, handle, variant: variantOverride, leading, trailing, compact, size, params, whenSubmitted, style, defaultFormOpen, "data-panel-tier": panelTier, }: DefaultInteractionButtonProps<Params>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=DefaultInteractionButton.d.ts.map

package/dist/components/surfaces/internal/DefaultInteractionButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultInteractionButton.d.ts","sourceRoot":"","sources":["../../../../src/components/surfaces/internal/DefaultInteractionButton.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAQ5E,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,6BAA6B,CAC5C,MAAM,SAAS,sBAAsB,GAAG,sBAAsB;IAE9D,UAAU,EAAE,qBAAqB,CAAC;IAClC,MAAM,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAClC,gEAAgE;IAChE,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC,sEAAsE;IACtE,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,SAAS,sBAAsB,GAAG,sBAAsB,EAC9D,EACA,UAAU,EACV,MAAM,EACN,OAAO,EAAE,eAAe,EACxB,OAAO,EACP,QAAQ,EACR,OAAO,EACP,IAAI,EACJ,MAAM,EACN,aAAa,EACb,KAAK,EACL,eAAuB,EACvB,iBAAiB,EAAE,SAAS,GAC7B,EAAE,6BAA6B,CAAC,MAAM,CAAC,2CA8GvC"}

package/dist/components/surfaces/internal/DefaultInteractionButton.js

@@ -0,0 +1,82 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { useTheme } from "../../../theme/ThemeProvider.js";
+import { InteractionForm, hasDefaultInteractionFormFields, } from "../../InteractionForm.js";
+import { interactionLabel } from "../../../utils/interaction-labels.js";
+import { ThemedButton } from "../../ThemedButton.js";
+/**
+ * @see DefaultInteractionButtonProps
+ */
+export function DefaultInteractionButton({ descriptor, handle, variant: variantOverride, leading, trailing, compact, size, params, whenSubmitted, style, defaultFormOpen = false, "data-panel-tier": panelTier, }) {
+    const theme = useTheme();
+    const [pending, setPending] = useState(false);
+    const [formOpen, setFormOpen] = useState(defaultFormOpen);
+    const submitted = handle.status === "submitted";
+    const fallbackLabel = interactionLabel(descriptor);
+    const variant = submitted
+        ? (whenSubmitted?.variant ?? "submitted")
+        : (variantOverride ?? "secondary");
+    const disabled = submitted ||
+        !descriptor.available ||
+        pending ||
+        handle.status === "submitting";
+    const needsForm = hasDefaultInteractionFormFields(descriptor);
+    const label = submitted
+        ? (whenSubmitted?.label ?? fallbackLabel)
+        : fallbackLabel;
+    const tooltip = descriptor.available
+        ? undefined
+        : formatUnavailableReason(descriptor.unavailableReason);
+    // Resolve size with the historical default — `compact` keeps `sm`
+    // for grouped sub-rows so existing call sites that rely on the
+    // tighter geometry don't change. Otherwise honour the explicit
+    // `size` prop, falling back to `md`.
+    const resolvedSize = size ?? (compact ? "sm" : "md");
+    const button = (_jsxs(ThemedButton, { type: "button", variant: variant, size: resolvedSize, pressed: pending || handle.status === "submitting", "aria-label": typeof label === "string" ? label : fallbackLabel, "aria-expanded": needsForm ? formOpen : undefined, "aria-disabled": disabled || undefined, "data-interaction-id": descriptor.interactionId, "data-emphasis": "secondary", "data-panel-tier": panelTier, "data-available": descriptor.available && !submitted ? "true" : "false", "data-action-state": submitted
+            ? "submitted"
+            : handle.status === "submitting"
+                ? "submitting"
+                : descriptor.available
+                    ? "available"
+                    : "unavailable", title: tooltip, disabled: disabled, style: style, onClick: async (event) => {
+            event.preventDefault();
+            if (disabled)
+                return;
+            if (needsForm) {
+                setFormOpen((open) => !open);
+                return;
+            }
+            setPending(true);
+            try {
+                if (params !== undefined) {
+                    await handle.submit(params);
+                }
+                else {
+                    await handle.submitDraft();
+                }
+            }
+            catch {
+                // Descriptor-level availability is authoritative; submission
+                // errors flow through the runtime's error channel. We swallow
+                // here so consumers without an error boundary don't see an
+                // unhandled rejection warning.
+            }
+            finally {
+                setPending(false);
+            }
+        }, children: [leading, submitted && whenSubmitted?.icon ? (_jsx("span", { "aria-hidden": true, style: { fontSize: "1.1em" }, children: whenSubmitted.icon })) : null, _jsx("span", { children: label }), trailing] }));
+    if (!needsForm)
+        return button;
+    return (_jsxs("span", { "data-default-interaction": true, style: {
+            display: "inline-flex",
+            flexDirection: "column",
+            alignItems: "stretch",
+            gap: theme.space[2],
+        }, children: [button, formOpen ? (_jsx(InteractionForm, { descriptor: descriptor, handle: handle, onCancel: () => setFormOpen(false), onSubmitSuccess: () => setFormOpen(false) })) : null] }));
+}
+function formatUnavailableReason(reason) {
+    if (reason === "INSUFFICIENT_RESOURCES") {
+        return "Insufficient resources";
+    }
+    return reason;
+}

package/dist/components/surfaces/internal/useCardZoneInteractions.d.ts

@@ -0,0 +1,21 @@
+import type { InteractionDescriptor } from "../../../types/plugin-state.js";
+import type { InteractionActionState, InteractionDisabledReason } from "../../../utils/interaction-status.js";
+import type { ViewCard } from "@dreamboard/sdk-types";
+export interface CardZoneInteractionContext<I extends string = string> {
+    card: ViewCard;
+    interactions: ReadonlyArray<InteractionDescriptor<I>>;
+    play: ((params?: Record<string, unknown>) => Promise<void>) | null;
+    disabled: boolean;
+    disabledReason?: InteractionDisabledReason;
+    actionState: InteractionActionState;
+    selected: boolean;
+}
+export declare function useCardZoneInteractions<I extends string = string>(zoneId: string, _options: {
+    surface: "hand" | "market";
+}): {
+    cards: readonly ViewCard<string, string, Record<string, unknown>>[];
+    contexts: readonly CardZoneInteractionContext<I>[];
+    followUp: InteractionDescriptor<I> | null;
+    setFollowUp: import("react").Dispatch<import("react").SetStateAction<InteractionDescriptor<I> | null>>;
+};
+//# sourceMappingURL=useCardZoneInteractions.d.ts.map

package/dist/components/surfaces/internal/useCardZoneInteractions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCardZoneInteractions.d.ts","sourceRoot":"","sources":["../../../../src/components/surfaces/internal/useCardZoneInteractions.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,qBAAqB,EAEtB,MAAM,gCAAgC,CAAC;AAUxC,OAAO,KAAK,EACV,sBAAsB,EACtB,yBAAyB,EAC1B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,MAAM,WAAW,0BAA0B,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACnE,IAAI,EAAE,QAAQ,CAAC;IACf,YAAY,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;IACnE,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,yBAAyB,CAAC;IAC3C,WAAW,EAAE,sBAAsB,CAAC;IACpC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAC/D,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE;IAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAA;CAAE;;;;;EA0NzC"}

package/dist/components/surfaces/internal/useCardZoneInteractions.js

@@ -0,0 +1,202 @@
+import { useCallback, useMemo, useState } from "react";
+import { useStore } from "zustand";
+import { useInteractionUiStore } from "../../../context/InteractionDraftContext.js";
+import { usePluginSession } from "../../../context/PluginSessionContext.js";
+import { usePluginState } from "../../../context/PluginStateContext.js";
+import { useRuntimeContext } from "../../../context/RuntimeContext.js";
+import { hasInteractionFieldErrors, inputByTarget, interactionArmScope, interactionInputKeys, isInputValueReady, toggleManyValue, validateInteractionInputDomains, } from "../../../utils/interaction-inputs.js";
+export function useCardZoneInteractions(zoneId, _options) {
+    const runtime = useRuntimeContext();
+    const { controllingPlayerId } = usePluginSession();
+    const draftStore = useInteractionUiStore();
+    const draftSnapshot = useStore(draftStore, (state) => state.drafts);
+    const submittingSnapshot = useStore(draftStore, (state) => state.submitting);
+    const [followUp, setFollowUp] = useState(null);
+    const zone = usePluginState((s) => s.gameplay.zones?.[zoneId]);
+    const simultaneousPhase = usePluginState((s) => s.gameplay.simultaneousPhase);
+    const cards = useMemo(() => {
+        if (!zone)
+            return [];
+        const list = [];
+        for (const cardId of zone.cardIds) {
+            const serialized = zone.cardsById[cardId];
+            if (!serialized)
+                continue;
+            try {
+                list.push(JSON.parse(serialized));
+            }
+            catch {
+                // Skip malformed card snapshots defensively.
+            }
+        }
+        return list;
+    }, [zone]);
+    const submitInteractionDraft = useCallback(async (descriptor, params) => {
+        if (!controllingPlayerId)
+            return;
+        if (draftStore.isSubmitting(descriptor.interactionKey))
+            return;
+        draftStore.setSubmitting(descriptor.interactionKey, true);
+        try {
+            await runtime.submitInteraction(controllingPlayerId, descriptor.interactionId, params);
+            draftStore.clearInput(descriptor.interactionKey);
+            const armScope = interactionArmScope(descriptor);
+            if (draftStore.getArmed(armScope) === descriptor.interactionKey) {
+                draftStore.arm(armScope, null);
+            }
+        }
+        finally {
+            draftStore.setSubmitting(descriptor.interactionKey, false);
+        }
+    }, [controllingPlayerId, draftStore, runtime]);
+    const playCardInteraction = useCallback(async (card, descriptor, params) => {
+        if (!controllingPlayerId)
+            return;
+        const cardInput = resolveCardInput(descriptor, card.id);
+        if (!cardInput)
+            return;
+        const cardInputKey = cardInput.key;
+        const currentDraft = draftStore.getDraft(descriptor.interactionKey);
+        const nextCardValue = cardInput.domain.type === "target" &&
+            cardInput.domain.selection?.mode === "many"
+            ? toggleManyValue(currentDraft[cardInputKey], card.id, cardInput.domain.selection)
+            : card.id;
+        const nextDraft = {
+            ...currentDraft,
+            ...(params ?? {}),
+            [cardInputKey]: nextCardValue,
+        };
+        for (const [key, value] of Object.entries(params ?? {})) {
+            draftStore.setInput(descriptor.interactionKey, key, value);
+        }
+        draftStore.setInput(descriptor.interactionKey, cardInputKey, nextCardValue);
+        if (cardInput.domain.type === "target" &&
+            cardInput.domain.selection?.mode === "many") {
+            if (descriptor.commit.mode === "autoWhenReady" &&
+                isDraftReady(descriptor, nextDraft)) {
+                await submitInteractionDraft(descriptor, nextDraft);
+            }
+            return;
+        }
+        const remaining = descriptor.inputs.filter((input) => {
+            const value = nextDraft[input.key] ??
+                ("defaultValue" in input ? input.defaultValue : undefined);
+            return input.key !== cardInputKey && value === undefined;
+        });
+        const needsBoardTarget = descriptor.inputs.some((input) => {
+            const value = nextDraft[input.key] ??
+                ("defaultValue" in input ? input.defaultValue : undefined);
+            return (input.key !== cardInputKey &&
+                input.domain.type === "target" &&
+                value === undefined);
+        });
+        if (needsBoardTarget) {
+            setFollowUp(null);
+            draftStore.arm(interactionArmScope(descriptor), descriptor.interactionKey);
+            return;
+        }
+        if (remaining.length > 0) {
+            setFollowUp(descriptor);
+            return;
+        }
+        if (!isDraftReady(descriptor, nextDraft) ||
+            descriptor.commit.mode !== "autoWhenReady") {
+            setFollowUp(null);
+            draftStore.arm(interactionArmScope(descriptor), descriptor.interactionKey);
+            return;
+        }
+        await submitInteractionDraft(descriptor, nextDraft);
+    }, [controllingPlayerId, draftStore, submitInteractionDraft]);
+    const contexts = useMemo(() => {
+        if (!zone)
+            return [];
+        return cards.map((card) => {
+            const interactions = zone.playableByCardId[card.id] ?? [];
+            const submittedInteraction = interactions.find((d) => controllingPlayerId !== null &&
+                simultaneousPhase?.phaseName === d.phaseName &&
+                simultaneousPhase.interactionId === d.interactionId &&
+                simultaneousPhase.sealedPlayerIds.includes(controllingPlayerId));
+            const submittingInteraction = interactions.find((d) => draftStore.isSubmitting(d.interactionKey));
+            const selected = interactions.some((d) => isCardSelected(d, card.id, draftStore.getDraft(d.interactionKey)));
+            const blockedState = submittedInteraction
+                ? "submitted"
+                : submittingInteraction
+                    ? "submitting"
+                    : null;
+            const available = blockedState
+                ? []
+                : interactions.filter((d) => d.available !== false &&
+                    isCardInteractionSelectable(d, card.id, draftStore.getDraft(d.interactionKey)));
+            const first = available.length === 1 ? available[0] : undefined;
+            const limited = !blockedState &&
+                interactions.some((d) => d.available !== false &&
+                    !isCardInteractionSelectable(d, card.id, draftStore.getDraft(d.interactionKey)));
+            const disabled = blockedState !== null || available.length === 0;
+            return {
+                card,
+                interactions,
+                play: first
+                    ? (params) => playCardInteraction(card, first, params)
+                    : null,
+                disabled,
+                disabledReason: blockedState ??
+                    (limited ? "selection-limit" : disabled ? "unavailable" : undefined),
+                actionState: blockedState ?? (disabled ? "unavailable" : "available"),
+                selected,
+            };
+        });
+    }, [
+        cards,
+        controllingPlayerId,
+        draftSnapshot,
+        draftStore,
+        playCardInteraction,
+        simultaneousPhase,
+        submittingSnapshot,
+        zone,
+    ]);
+    return { cards, contexts, followUp, setFollowUp };
+}
+function isCardSelected(descriptor, cardId, draft) {
+    const input = resolveCardInput(descriptor, cardId);
+    if (!input)
+        return false;
+    const current = draft[input.key];
+    return Array.isArray(current)
+        ? current.map((item) => String(item)).includes(cardId)
+        : String(current) === cardId;
+}
+function isCardInteractionSelectable(descriptor, cardId, draft) {
+    const input = resolveCardInput(descriptor, cardId);
+    if (!input || input.domain.type !== "target")
+        return true;
+    const selection = input.domain.selection;
+    if (selection?.mode !== "many" || !selection.distinct)
+        return true;
+    const current = draft[input.key];
+    if (!Array.isArray(current))
+        return true;
+    if (current.map((item) => String(item)).includes(cardId))
+        return true;
+    return selection.max === undefined || current.length < selection.max;
+}
+function isDraftReady(descriptor, draft) {
+    const fieldErrors = validateInteractionInputDomains(descriptor, draft);
+    if (hasInteractionFieldErrors(fieldErrors))
+        return false;
+    return interactionInputKeys(descriptor).every((key) => {
+        const input = descriptor.inputs.find((candidate) => candidate.key === key);
+        const value = draft[key] ??
+            (input && "defaultValue" in input ? input.defaultValue : undefined);
+        return input ? isInputValueReady(input, value) : value !== undefined;
+    });
+}
+function resolveCardInput(descriptor, cardId) {
+    const targetInput = inputByTarget(descriptor, "card", cardId);
+    if (targetInput)
+        return targetInput;
+    if (interactionInputKeys(descriptor).includes("cardId")) {
+        return descriptor.inputs.find((input) => input.key === "cardId") ?? null;
+    }
+    return null;
+}

package/dist/components/surfaces/types.d.ts

@@ -0,0 +1,59 @@
+import type { ReactNode } from "react";
+import type { InteractionHandle, InteractionParamsShape } from "../../hooks/useInteractionHandle.js";
+import type { InteractionDescriptor } from "../../types/plugin-state.js";
+import type { SubmittedActionConfig } from "./internal/DefaultInteractionButton.js";
+export type InteractionParamsByKeyShape = Record<string, InteractionParamsShape | {
+    params: InteractionParamsShape;
+    defaulted?: string;
+}>;
+export type InteractionParamsOf<ParamsByKey extends Partial<InteractionParamsByKeyShape>, Key extends string> = Key extends keyof ParamsByKey ? ParamsByKey[Key] extends {
+    params: infer Params extends InteractionParamsShape;
+} ? Params : ParamsByKey[Key] extends InteractionParamsShape ? ParamsByKey[Key] : InteractionParamsShape : InteractionParamsShape;
+export type InteractionDefaultedKeysOf<ParamsByKey extends Partial<InteractionParamsByKeyShape>, Key extends string> = Key extends keyof ParamsByKey ? ParamsByKey[Key] extends {
+    defaulted?: infer Defaulted extends string;
+} ? Extract<Defaulted, keyof InteractionParamsOf<ParamsByKey, Key> & string> : never : never;
+/**
+ * Per-interaction renderer overrides for a surface. Partial: when omitted
+ * entirely, the surface uses its built-in default renderer for every
+ * interaction. When present, every key MUST be a valid member of `I` —
+ * typos are a compile-time error against the generated `*Interactions`
+ * id alias from `@dreamboard/ui-contract`.
+ *
+ * ```ts
+ * import type { PanelInteractions } from "@dreamboard/ui-contract";
+ *
+ * <PanelSurface<PanelInteractions> render={{ rollDice: ... }} />
+ * // ✗ <PanelSurface<PanelInteractions> render={{ rolldice: ... }} />
+ * //                                              ^^^^^^^^^ typo: not assignable
+ * ```
+ *
+ * If you want compile-time exhaustiveness (every interaction id in `I`
+ * must have an explicit renderer), use {@link ExhaustiveSurfaceRenderMap}
+ * instead.
+ */
+export interface DefaultInteractionRenderConfig {
+    whenSubmitted?: SubmittedActionConfig;
+}
+export type SurfaceRenderEntry<D, H> = ((descriptor: D, handle: H) => ReactNode) | DefaultInteractionRenderConfig;
+export type SurfaceRenderMap<I extends string, ParamsByKey extends Partial<InteractionParamsByKeyShape> = {}> = {
+    [K in I]?: SurfaceRenderEntry<InteractionDescriptor<K>, InteractionHandle<InteractionParamsOf<ParamsByKey, K>, InteractionDefaultedKeysOf<ParamsByKey, K>>>;
+};
+/**
+ * Exhaustive (required) variant of {@link SurfaceRenderMap}. Every key of
+ * `I` MUST have an explicit renderer — useful when authors want the
+ * compiler to enforce that no interaction id slips through without a
+ * deliberate visual treatment.
+ *
+ * ```ts
+ * import type { PanelInteractions } from "@dreamboard/ui-contract";
+ * import type { ExhaustiveSurfaceRenderMap } from "@dreamboard/ui-sdk";
+ *
+ * const panelRenderers: ExhaustiveSurfaceRenderMap<PanelInteractions> = {
+ *   rollDice: ...,
+ *   buildSettlement: ...,
+ *   // omitting any id here is a compile-time error
+ * };
+ * ```
+ */
+export type ExhaustiveSurfaceRenderMap<I extends string, ParamsByKey extends Partial<InteractionParamsByKeyShape> = {}> = Required<SurfaceRenderMap<I, ParamsByKey>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/components/surfaces/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/surfaces/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAEpF,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAC9C,MAAM,EACJ,sBAAsB,GACtB;IACE,MAAM,EAAE,sBAAsB,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CACJ,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAC7B,WAAW,SAAS,OAAO,CAAC,2BAA2B,CAAC,EACxD,GAAG,SAAS,MAAM,IAChB,GAAG,SAAS,MAAM,WAAW,GAC7B,WAAW,CAAC,GAAG,CAAC,SAAS;IACvB,MAAM,EAAE,MAAM,MAAM,SAAS,sBAAsB,CAAC;CACrD,GACC,MAAM,GACN,WAAW,CAAC,GAAG,CAAC,SAAS,sBAAsB,GAC7C,WAAW,CAAC,GAAG,CAAC,GAChB,sBAAsB,GAC1B,sBAAsB,CAAC;AAE3B,MAAM,MAAM,0BAA0B,CACpC,WAAW,SAAS,OAAO,CAAC,2BAA2B,CAAC,EACxD,GAAG,SAAS,MAAM,IAChB,GAAG,SAAS,MAAM,WAAW,GAC7B,WAAW,CAAC,GAAG,CAAC,SAAS;IAAE,SAAS,CAAC,EAAE,MAAM,SAAS,SAAS,MAAM,CAAA;CAAE,GACrE,OAAO,CAAC,SAAS,EAAE,MAAM,mBAAmB,CAAC,WAAW,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,GACxE,KAAK,GACP,KAAK,CAAC;AAEV;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,8BAA8B;IAC7C,aAAa,CAAC,EAAE,qBAAqB,CAAC;CACvC;AAED,MAAM,MAAM,kBAAkB,CAAC,CAAC,EAAE,CAAC,IAC/B,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,SAAS,CAAC,GACzC,8BAA8B,CAAC;AAEnC,MAAM,MAAM,gBAAgB,CAC1B,CAAC,SAAS,MAAM,EAChB,WAAW,SAAS,OAAO,CAAC,2BAA2B,CAAC,GAAG,EAAE,IAC3D;KACD,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,kBAAkB,CAC3B,qBAAqB,CAAC,CAAC,CAAC,EACxB,iBAAiB,CACf,mBAAmB,CAAC,WAAW,EAAE,CAAC,CAAC,EACnC,0BAA0B,CAAC,WAAW,EAAE,CAAC,CAAC,CAC3C,CACF;CACF,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,0BAA0B,CACpC,CAAC,SAAS,MAAM,EAChB,WAAW,SAAS,OAAO,CAAC,2BAA2B,CAAC,GAAG,EAAE,IAC3D,QAAQ,CAAC,gBAAgB,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC"}

package/dist/components/surfaces/types.js

@@ -0,0 +1 @@
+export {};

package/dist/context/ClientParamSchemaContext.d.ts

@@ -0,0 +1,21 @@
+export interface ClientParamSchema {
+    safeParse: (value: unknown) => {
+        success: true;
+        data: Record<string, unknown>;
+    } | {
+        success: false;
+        error: {
+            issues: ReadonlyArray<{
+                path: readonly PropertyKey[];
+                message: string;
+            }>;
+        };
+    };
+}
+export type ClientParamSchemaMap = Readonly<Record<string, Readonly<Record<string, ClientParamSchema>>>>;
+export declare function ClientParamSchemaProvider({ schemas, children, }: {
+    schemas?: ClientParamSchemaMap;
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useClientParamSchema(phaseName: string | null | undefined, interactionId: string): ClientParamSchema | undefined;
+//# sourceMappingURL=ClientParamSchemaContext.d.ts.map

package/dist/context/ClientParamSchemaContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientParamSchemaContext.d.ts","sourceRoot":"","sources":["../../src/context/ClientParamSchemaContext.tsx"],"names":[],"mappings":"AAEA,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KACtB;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAChD;QACE,OAAO,EAAE,KAAK,CAAC;QACf,KAAK,EAAE;YACL,MAAM,EAAE,aAAa,CAAC;gBACpB,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;gBAC7B,OAAO,EAAE,MAAM,CAAC;aACjB,CAAC,CAAC;SACJ,CAAC;KACH,CAAC;CACP;AAED,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CACzC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAC5D,CAAC;AAIF,wBAAgB,yBAAyB,CAAC,EACxC,OAAO,EACP,QAAQ,GACT,EAAE;IACD,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,2CAMA;AAED,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,aAAa,EAAE,MAAM,GACpB,iBAAiB,GAAG,SAAS,CAI/B"}

package/dist/context/ClientParamSchemaContext.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const ClientParamSchemaContext = createContext({});
+export function ClientParamSchemaProvider({ schemas, children, }) {
+    return (_jsx(ClientParamSchemaContext.Provider, { value: schemas ?? {}, children: children }));
+}
+export function useClientParamSchema(phaseName, interactionId) {
+    const schemas = useContext(ClientParamSchemaContext);
+    if (!phaseName)
+        return undefined;
+    return schemas[phaseName]?.[interactionId];
+}

package/dist/context/InteractionDraftContext.d.ts

@@ -0,0 +1,69 @@
+import { type ReactNode } from "react";
+import { type StoreApi } from "zustand/vanilla";
+type Draft = Readonly<Record<string, unknown>>;
+interface DraftState {
+    drafts: Readonly<Record<string, Draft>>;
+    arms: Readonly<Record<string, string>>;
+    submitting: Readonly<Record<string, true>>;
+}
+/**
+ * Imperative API exposed to `useInteractionHandle` and `<BoardSurface>`.
+ * Intentionally small; the vanilla zustand store underneath powers
+ * fine-grained subscriptions via {@link useDraft} and {@link useArmed}.
+ */
+export interface InteractionUiStore {
+    /** Read the current draft for an interaction id. Never undefined. */
+    getDraft(interactionId: string): Draft;
+    /** Merge a single input key into the draft. Creates the draft if needed. */
+    setInput(interactionId: string, key: string, value: unknown): void;
+    /** Clear a single input, or the whole draft if `key` is omitted. */
+    clearInput(interactionId: string, key?: string): void;
+    /** Clear every draft and arming state. */
+    clearAll(): void;
+    /** Which interaction (if any) is currently armed on the given surface. */
+    getArmed(surface: string): string | null;
+    /** Arm a specific interaction on a surface. Pass `null` to disarm. */
+    arm(surface: string, interactionId: string | null): void;
+    /** True while a local submission is in flight before the host echo arrives. */
+    isSubmitting(interactionId: string): boolean;
+    /** Mark or clear a local submission in flight. */
+    setSubmitting(interactionId: string, submitting: boolean): void;
+}
+/** Vanilla zustand store implementing {@link InteractionUiStore}. */
+export type InteractionUiStoreApi = StoreApi<DraftState> & InteractionUiStore;
+export declare function createInteractionUiStore(): InteractionUiStoreApi;
+/**
+ * React provider that holds draft input state shared across every surface
+ * inside the tree. Auto-installed by `<PluginRuntime>`; authors rarely
+ * mount it directly. Mount manually when rendering surface components in
+ * isolation (e.g., Storybook, snapshot tests).
+ *
+ * ```tsx
+ * <InteractionUiProvider>
+ *   <PanelSurface />
+ *   <BoardSurface>{(ctx) => <Board ctx={ctx} />}</BoardSurface>
+ * </InteractionUiProvider>
+ * ```
+ */
+export declare function InteractionUiProvider({ children, store, }: {
+    children: ReactNode;
+    store?: InteractionUiStoreApi;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Access the active draft store. Falls back to an inert in-memory store
+ * when no provider is mounted, so surface hooks remain callable in bare
+ * test harnesses without crashing — draft state simply isn't shared
+ * across components in that case.
+ */
+export declare function useInteractionUiStore(): InteractionUiStoreApi;
+/**
+ * Subscribe to the draft for a single interaction id with per-slice
+ * re-renders. Returns a stable empty object when the draft is unset.
+ */
+export declare function useInteractionDraft(interactionId: string): Draft;
+/** Subscribe to the armed interaction id on a given surface. */
+export declare function useArmedInteraction(surface: string): string | null;
+/** Subscribe to local submitting status for a single interaction key. */
+export declare function useInteractionSubmitting(interactionId: string): boolean;
+export {};
+//# sourceMappingURL=InteractionDraftContext.d.ts.map

package/dist/context/InteractionDraftContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InteractionDraftContext.d.ts","sourceRoot":"","sources":["../../src/context/InteractionDraftContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE3E,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAG7D,KAAK,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAI/C,UAAU,UAAU;IAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;IACxC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,KAAK,CAAC;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACnE,oEAAoE;IACpE,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD,0CAA0C;IAC1C,QAAQ,IAAI,IAAI,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACzC,sEAAsE;IACtE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IACzD,+EAA+E;IAC/E,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7C,kDAAkD;IAClD,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;CACjE;AAED,qEAAqE;AACrE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,kBAAkB,CAAC;AAE9E,wBAAgB,wBAAwB,IAAI,qBAAqB,CA0FhE;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,QAAQ,EACR,KAAK,GACN,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,CAAC,EAAE,qBAAqB,CAAC;CAC/B,2CAOA;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,qBAAqB,CAI7D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,KAAK,CAQhE;AAED,gEAAgE;AAChE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGlE;AAED,yEAAyE;AACzE,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAMvE"}