@jini-ai/ui-kit 0.0.0-stage → 0.1.1

package/dist/react/native/index.d.ts

@@ -0,0 +1,3 @@
+import type { ReactKit } from '../types.js';
+export declare const nativeKit: ReactKit;
+//# sourceMappingURL=index.d.ts.map

package/dist/react/native/index.js

@@ -0,0 +1,9 @@
+import { NativeButton, NativeIconButton, NativeTextField, NativeTextArea, NativeSelect, NativeCheckbox, NativeSwitch, NativeToast, NativeNotice, NativeSpinner, NativeBadge } from './Controls.js';
+import { NativeDialog, NativeConfirmDialog } from './Dialog.js';
+import { NativeTabs, NativeMenu, NativeTooltip } from './Navigation.js';
+export const nativeKit = Object.freeze({ Button: NativeButton, IconButton: NativeIconButton,
+    TextField: NativeTextField, TextArea: NativeTextArea, Select: NativeSelect, Checkbox: NativeCheckbox,
+    Switch: NativeSwitch, Dialog: NativeDialog, ConfirmDialog: NativeConfirmDialog, Tabs: NativeTabs,
+    Menu: NativeMenu, Toast: NativeToast, Tooltip: NativeTooltip, Notice: NativeNotice, Spinner: NativeSpinner, Badge: NativeBadge });
+// This is a concrete kit, rather than a forwarding subpath to another package's implementation.
+//# sourceMappingURL=index.js.map

package/dist/react/testing/driver.d.ts

@@ -0,0 +1,27 @@
+import type { AgentAttrsPort } from '../../attrs.js';
+import type { KitScenario } from '../../testing/scenarios.js';
+import type { ImplementedComponentName } from '../../kit.spec.js';
+import type { ResolvedKit } from '../types.js';
+export interface KitConformanceResult {
+    readonly id: string;
+    readonly status: 'passed' | 'failed' | 'skipped';
+    readonly errors: readonly string[];
+}
+export interface KitConformanceDriver {
+    run(required: {
+        kit: ResolvedKit;
+        scenario: KitScenario;
+        agent: AgentAttrsPort;
+    }, optional?: Record<string, never>): Promise<readonly string[]>;
+}
+export declare const reactConformanceDriver: KitConformanceDriver;
+export declare function runKitConformance(required: {
+    kit: ResolvedKit;
+}, optional?: {
+    driver?: KitConformanceDriver;
+    agent?: AgentAttrsPort;
+    only?: readonly ImplementedComponentName[];
+    scenarios?: readonly KitScenario[];
+    includeBrowser?: boolean;
+}): Promise<readonly KitConformanceResult[]>;
+//# sourceMappingURL=driver.d.ts.map

package/dist/react/testing/driver.js

@@ -0,0 +1,102 @@
+import { act, createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { KitProvider } from '../KitProvider.js';
+import * as facades from '../facade.js';
+import { ConfirmDialog } from '../confirm/ConfirmDialog.js';
+import { describeKit } from '../kit.js';
+import { kitConformanceScenarios } from '../../testing/scenarios.js';
+const testingAgent = ({ handle }, options = {}) => ({ 'data-agent-element': handle, 'data-agent-role': options.role, 'data-agent-label': options.label });
+function fixture(scenario, calls) {
+    const count = (name) => () => { calls[name] = (calls[name] ?? 0) + 1; };
+    const common = { children: 'Example', label: 'Example', value: 'a', checked: true, message: 'Saved', content: 'Help',
+        open: true, title: 'Delete record?', confirmLabel: 'Delete', body: 'Example record',
+        options: [{ value: 'a', label: 'Alpha' }, { value: 'b', label: 'Beta' }],
+        items: scenario.component === 'Menu' ? [{ id: 'a', label: 'Alpha', onPress: count('item') }] : [{ id: 'a', label: 'Alpha', content: 'Alpha panel' }],
+        onPress: count('press'), onValueChange: count('change'), onCheckedChange: count('change'), onClose: count('cancel'),
+        onConfirm: count('confirm'), onCancel: count('cancel'), ...scenario.props };
+    const Component = scenario.component === 'ConfirmDialog' ? ConfirmDialog : facades[scenario.component];
+    // The scenario union intentionally carries framework-neutral props; the driver performs the binding.
+    return createElement(Component, common);
+}
+function check(expectation, root, calls) {
+    if (expectation.type === 'calls')
+        return (calls[expectation.name] ?? 0) === expectation.count ? undefined : `${expectation.name} calls: expected ${expectation.count}, received ${calls[expectation.name] ?? 0}`;
+    const element = root.querySelector(expectation.selector);
+    if (expectation.type === 'absent')
+        return element ? `unexpected ${expectation.selector}` : undefined;
+    if (!element)
+        return `missing ${expectation.selector}`;
+    if (expectation.type === 'attribute')
+        return element.getAttribute(expectation.name) === expectation.value ? undefined : `${expectation.selector} did not forward ${expectation.name}=${expectation.value}`;
+    if (expectation.type === 'focused')
+        return element === document.activeElement ? undefined : `${expectation.selector} not focused`;
+    if (expectation.type === 'disabled')
+        return element.matches(':disabled') || element.getAttribute('aria-disabled') === 'true' ? undefined : `${expectation.selector} not disabled`;
+    if (expectation.type === 'native-select')
+        return element instanceof HTMLSelectElement ? undefined : 'Select must render HTMLSelectElement';
+    if (expectation.type === 'focusable')
+        return element.matches('button,input,select,textarea,[tabindex]') ? undefined : `${expectation.selector} is not focusable`;
+}
+export const reactConformanceDriver = {
+    async run({ kit, scenario, agent }) {
+        if (typeof document === 'undefined')
+            throw new Error('React conformance requires a DOM environment');
+        const host = document.createElement('div'), overlay = document.createElement('div'), calls = {};
+        document.body.append(host, overlay);
+        const root = createRoot(host), errors = [];
+        const before = describeKit({ kit }).violations.length;
+        try {
+            // Never let the dev guard make a broken adapter pass conformance by silently substituting native.
+            await act(async () => { root.render(createElement(KitProvider, { kit, agent, overlayContainer: overlay, guard: 'off', children: fixture(scenario, calls) })); });
+            for (const action of scenario.actions) {
+                const element = (host.querySelector(action.selector) ?? overlay.querySelector(action.selector));
+                if (!element) {
+                    errors.push(`action target missing: ${action.selector}`);
+                    continue;
+                }
+                await act(async () => {
+                    if (action.type === 'click')
+                        element.click();
+                    else if (action.type === 'focus')
+                        element.focus();
+                    else if (action.type === 'cancel')
+                        element.dispatchEvent(new Event('cancel', { bubbles: false, cancelable: true }));
+                    else
+                        element.dispatchEvent(new KeyboardEvent('keydown', { key: action.key ?? '', bubbles: true, cancelable: true }));
+                });
+            }
+            for (const expectation of scenario.expectations) {
+                const scope = expectation.type === 'calls' || host.querySelector(expectation.selector) ? host : overlay;
+                const error = check(expectation, scope, calls);
+                if (error)
+                    errors.push(error);
+            }
+            if (describeKit({ kit }).violations.length !== before)
+                errors.push('conformance must not trigger fallback');
+        }
+        finally {
+            await act(async () => root.unmount());
+            host.remove();
+            overlay.remove();
+        }
+        return errors;
+    },
+};
+export async function runKitConformance(required, optional = {}) {
+    const driver = optional.driver ?? reactConformanceDriver;
+    if (optional.includeBrowser && driver === reactConformanceDriver)
+        throw new Error('Browser cases require a real browser driver');
+    const results = [];
+    for (const scenario of optional.scenarios ?? kitConformanceScenarios) {
+        if (optional.only && !optional.only.includes(scenario.component))
+            continue;
+        if (scenario.browserOnly && !optional.includeBrowser) {
+            results.push({ id: scenario.id, status: 'skipped', errors: ['requires real browser driver'] });
+            continue;
+        }
+        const errors = await driver.run({ kit: required.kit, scenario, agent: optional.agent ?? testingAgent });
+        results.push({ id: scenario.id, status: errors.length ? 'failed' : 'passed', errors });
+    }
+    return results;
+}
+//# sourceMappingURL=driver.js.map

package/dist/react/testing/index.d.ts

@@ -0,0 +1,5 @@
+export { kitConformanceScenarios } from '../../testing/scenarios.js';
+export type { KitScenario, ConformanceAction, ConformanceExpectation } from '../../testing/scenarios.js';
+export { runKitConformance, reactConformanceDriver } from './driver.js';
+export type { KitConformanceResult, KitConformanceDriver } from './driver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/react/testing/index.js

@@ -0,0 +1,3 @@
+export { kitConformanceScenarios } from '../../testing/scenarios.js';
+export { runKitConformance, reactConformanceDriver } from './driver.js';
+//# sourceMappingURL=index.js.map

package/dist/react/types.d.ts

@@ -0,0 +1,210 @@
+import type { ComponentType, ReactNode, Ref, RefObject, HTMLAttributes } from 'react';
+import type { KitAttrs, AgentAttrsPort } from '../attrs.js';
+import type { ConfirmInput, DismissReason } from '../confirm.js';
+import type { ImplementedComponentName } from '../kit.spec.js';
+import type { KitNeeds } from '../needs.js';
+import type { ToastService } from '../toast.js';
+export interface BaseProps {
+    readonly attrs?: KitAttrs;
+    readonly className?: string;
+}
+export type ActionPort = (required: Record<string, never>, optional?: Record<string, never>) => void;
+export type ValuePort<T> = (required: {
+    value: T;
+}, optional?: Record<string, never>) => void;
+export interface ButtonProps extends BaseProps {
+    readonly children?: ReactNode;
+    readonly onPress?: ActionPort;
+    readonly disabled?: boolean;
+    readonly pending?: boolean;
+    readonly variant?: 'primary' | 'secondary' | 'danger' | 'warning' | 'ghost';
+    readonly type?: 'button' | 'submit' | 'reset';
+    readonly ref?: Ref<HTMLButtonElement>;
+}
+export interface IconButtonProps extends ButtonProps {
+    readonly label: string;
+}
+export interface TextFieldProps extends BaseProps {
+    readonly label: string;
+    readonly value: string;
+    readonly onValueChange: ValuePort<string>;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly placeholder?: string;
+    readonly type?: 'text' | 'password' | 'email' | 'search' | 'url' | 'tel' | 'number';
+    readonly ref?: Ref<HTMLInputElement>;
+}
+export interface TextAreaProps extends Omit<TextFieldProps, 'type' | 'ref'> {
+    readonly rows?: number;
+    readonly ref?: Ref<HTMLTextAreaElement>;
+}
+export interface SelectOption {
+    readonly value: string;
+    readonly label: string;
+    readonly disabled?: boolean;
+}
+export interface SelectProps extends Omit<TextFieldProps, 'type' | 'placeholder' | 'ref'> {
+    readonly options: readonly SelectOption[];
+    readonly ref?: Ref<HTMLSelectElement>;
+}
+export interface CheckboxProps extends BaseProps {
+    readonly label: string;
+    readonly checked: boolean;
+    readonly onCheckedChange: (required: {
+        checked: boolean;
+    }, optional?: Record<string, never>) => void;
+    readonly disabled?: boolean;
+    readonly ref?: Ref<HTMLInputElement>;
+}
+export interface SwitchProps extends CheckboxProps {
+}
+export interface DialogProps extends BaseProps {
+    readonly open: boolean;
+    readonly title: string;
+    readonly children?: ReactNode;
+    readonly onClose: ActionPort;
+    readonly pending?: boolean;
+    readonly closeLabel?: string;
+    readonly ref?: Ref<HTMLDialogElement>;
+}
+export interface ConfirmDialogProps extends ConfirmInput, BaseProps {
+    readonly body?: ReactNode;
+    readonly onConfirm: (required: Record<string, never>, optional?: Record<string, never>) => void | Promise<void>;
+    readonly onCancel: ActionPort;
+    readonly errorLabel?: string;
+    /** Concise names opt in to describing the consequence separately, preserving agent labels. */
+    readonly actionAccessibleNames?: {
+        readonly cancel: string;
+        readonly confirm: string;
+    };
+}
+export interface ConfirmController {
+    readonly className?: string | undefined;
+    readonly nativeActions?: boolean;
+    readonly open: boolean;
+    readonly pending: boolean;
+    readonly title: string;
+    readonly body: ReactNode;
+    readonly consequence: string | undefined;
+    readonly error: ReactNode;
+    readonly titleAttrs: HTMLAttributes<HTMLHeadingElement>;
+    readonly consequenceAttrs?: HTMLAttributes<HTMLParagraphElement>;
+    readonly frameAttrs: KitAttrs & {
+        readonly role: 'alertdialog';
+        readonly 'aria-labelledby': string;
+    };
+    readonly cancel: ButtonProps;
+    readonly confirm: ButtonProps;
+    readonly boundaryRef: RefObject<HTMLSpanElement | null>;
+    readonly overlayContainer: HTMLElement | null;
+    readonly agentMayConfirm: boolean;
+    requestDismiss(required: {
+        reason: DismissReason;
+    }, optional?: Record<string, never>): boolean;
+    focusInitial(required: Record<string, never>, optional?: Record<string, never>): void;
+}
+/** Overrides receive a view model only. Raw destructive callbacks are never provided. */
+export interface ConfirmViewProps {
+    readonly controller: ConfirmController;
+}
+export interface TabItem {
+    readonly id: string;
+    readonly label: string;
+    readonly content: ReactNode;
+    readonly disabled?: boolean;
+    readonly attrs?: KitAttrs;
+}
+export interface TabsProps extends BaseProps {
+    readonly label: string;
+    readonly value: string;
+    readonly items: readonly TabItem[];
+    readonly onValueChange: ValuePort<string>;
+}
+export interface MenuItem {
+    readonly id: string;
+    readonly label: string;
+    readonly disabled?: boolean;
+    readonly onPress: ActionPort;
+    readonly attrs?: KitAttrs;
+}
+export interface MenuProps extends BaseProps {
+    readonly label: string;
+    readonly items: readonly MenuItem[];
+    readonly disabled?: boolean;
+}
+export interface ToastProps extends BaseProps {
+    readonly message: string;
+    readonly tone?: 'info' | 'success' | 'warning' | 'danger';
+    readonly onDismiss?: ActionPort;
+    readonly dismissLabel?: string;
+}
+export interface TooltipProps extends BaseProps {
+    readonly content: ReactNode;
+    readonly children: ReactNode;
+    readonly label?: string;
+}
+export interface NoticeProps extends BaseProps {
+    readonly children: ReactNode;
+    readonly tone?: 'info' | 'success' | 'warning' | 'danger';
+}
+export interface SpinnerProps extends BaseProps {
+    readonly label?: string;
+}
+export interface BadgeProps extends BaseProps {
+    readonly children: ReactNode;
+    readonly tone?: 'info' | 'success' | 'warning' | 'danger';
+}
+export interface ReactKitProps {
+    Button: ButtonProps;
+    IconButton: IconButtonProps;
+    TextField: TextFieldProps;
+    TextArea: TextAreaProps;
+    Select: SelectProps;
+    Checkbox: CheckboxProps;
+    Switch: SwitchProps;
+    Dialog: DialogProps;
+    ConfirmDialog: ConfirmViewProps;
+    Tabs: TabsProps;
+    Menu: MenuProps;
+    Toast: ToastProps;
+    Tooltip: TooltipProps;
+    Notice: NoticeProps;
+    Spinner: SpinnerProps;
+    Badge: BadgeProps;
+}
+export type ReactKit = {
+    readonly [K in ImplementedComponentName]: ComponentType<ReactKitProps[K]>;
+};
+export type GuardMode = 'fallback' | 'warn' | 'off';
+export interface KitViolation {
+    readonly component: ImplementedComponentName;
+    readonly reasons: readonly string[];
+}
+export interface ResolvedKit {
+    readonly id: string;
+    readonly contract: string;
+    readonly components: ReactKit;
+    readonly overrides: readonly ImplementedComponentName[];
+    readonly violations: KitViolation[];
+    readonly failed: Set<ImplementedComponentName>;
+    readonly guard: GuardMode;
+}
+export interface KitProviderProps {
+    readonly kit?: ResolvedKit;
+    readonly children: ReactNode;
+    readonly agent?: AgentAttrsPort;
+    readonly overlayContainer?: HTMLElement;
+    readonly needs?: readonly KitNeeds[];
+    readonly toast?: ToastService;
+    readonly cancelLabel?: string;
+    readonly guard?: GuardMode;
+}
+export interface KitContextValue {
+    readonly kit: ResolvedKit;
+    readonly agent: AgentAttrsPort | undefined;
+    readonly overlayContainer: HTMLElement | null;
+    readonly toast: ToastService | undefined;
+    readonly cancelLabel: string;
+    readonly guard: GuardMode;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/react/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/testing/scenarios.d.ts

@@ -0,0 +1,31 @@
+import type { ImplementedComponentName } from '../kit.spec.js';
+export type ConformanceAction = {
+    readonly type: 'click' | 'cancel' | 'focus' | 'key';
+    readonly selector: string;
+    readonly key?: string;
+};
+export type ConformanceExpectation = {
+    readonly type: 'attribute';
+    readonly selector: string;
+    readonly name: string;
+    readonly value: string;
+} | {
+    readonly type: 'focused' | 'disabled' | 'absent' | 'native-select' | 'focusable';
+    readonly selector: string;
+} | {
+    readonly type: 'calls';
+    readonly name: string;
+    readonly count: number;
+};
+export interface KitScenario {
+    readonly id: string;
+    readonly component: ImplementedComponentName;
+    readonly safety?: boolean;
+    readonly browserOnly?: boolean;
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly actions: readonly ConformanceAction[];
+    readonly expectations: readonly ConformanceExpectation[];
+}
+/** Serializable cases can drive another framework or a real-browser fixture without importing React. */
+export declare const kitConformanceScenarios: readonly KitScenario[];
+//# sourceMappingURL=scenarios.d.ts.map

package/dist/testing/scenarios.js

@@ -0,0 +1,28 @@
+/** Serializable cases can drive another framework or a real-browser fixture without importing React. */
+export const kitConformanceScenarios = Object.freeze([
+    ...['Button', 'IconButton', 'TextField', 'TextArea', 'Select', 'Checkbox', 'Switch', 'Dialog', 'Tabs', 'Menu', 'Toast', 'Tooltip', 'Notice', 'Spinner', 'Badge'].map(component => ({
+        id: `${component}:opaque-attrs`, component, props: { attrs: { 'data-agent-element': 'probe', 'data-jini-part': 'x.host.part', 'aria-description': 'opaque' } }, actions: [],
+        expectations: [{ type: 'focusable', selector: '[data-agent-element="probe"]' },
+            { type: 'attribute', selector: '[data-agent-element="probe"]', name: 'data-jini-part', value: 'x.host.part' },
+            { type: 'attribute', selector: '[data-agent-element="probe"]', name: 'aria-description', value: 'opaque' }],
+    })),
+    { id: 'Select:native-semantics', component: 'Select', props: {}, actions: [], expectations: [{ type: 'native-select', selector: '[data-jini-part="kit.select"]' }] },
+    { id: 'Button:disabled-blocks-press', component: 'Button', props: { disabled: true }, actions: [{ type: 'click', selector: 'button' }], expectations: [{ type: 'calls', name: 'press', count: 0 }] },
+    { id: 'ConfirmDialog:cancel-first-focus', component: 'ConfirmDialog', safety: true, props: {}, actions: [], expectations: [{ type: 'focused', selector: '[data-jini-part="confirm.cancel"]' }] },
+    { id: 'ConfirmDialog:pending-blocks-every-dismissal', component: 'ConfirmDialog', safety: true, props: { pending: true },
+        actions: [{ type: 'cancel', selector: '[data-jini-part="confirm.dialog"]' }, { type: 'click', selector: '[data-jini-part="confirm.dialog"]' },
+            { type: 'click', selector: '[data-jini-part="confirm.cancel"]' }, { type: 'click', selector: '[data-jini-part="confirm.confirm"]' }],
+        expectations: [{ type: 'calls', name: 'cancel', count: 0 }, { type: 'calls', name: 'confirm', count: 0 },
+            { type: 'disabled', selector: '[data-jini-part="confirm.cancel"]' }, { type: 'disabled', selector: '[data-jini-part="confirm.confirm"]' }] },
+    { id: 'ConfirmDialog:agent-confirm-withheld', component: 'ConfirmDialog', safety: true, props: { agentHandle: 'erase', agentMayConfirm: false }, actions: [],
+        expectations: [{ type: 'absent', selector: '[data-agent-element="erase-confirm"]' },
+            { type: 'attribute', selector: '[data-jini-part="confirm.cancel"]', name: 'data-agent-element', value: 'erase-cancel' }] },
+    { id: 'ConfirmDialog:consequence-label', component: 'ConfirmDialog', safety: true, props: { agentHandle: 'erase', tone: 'danger' }, actions: [],
+        expectations: [{ type: 'attribute', selector: '[data-jini-part="confirm.confirm"]', name: 'data-agent-label', value: 'Delete — Delete record?; cannot be undone' },
+            { type: 'attribute', selector: '[data-jini-part="confirm.confirm"]', name: 'aria-label', value: 'Delete — Delete record?; cannot be undone' }] },
+    { id: 'ConfirmDialog:browser-escape', component: 'ConfirmDialog', safety: true, browserOnly: true, props: {},
+        actions: [{ type: 'key', selector: '[data-jini-part="confirm.cancel"]', key: 'Escape' }], expectations: [{ type: 'calls', name: 'cancel', count: 1 }] },
+    { id: 'ConfirmDialog:browser-modal-focus', component: 'ConfirmDialog', safety: true, browserOnly: true, props: {}, actions: [],
+        expectations: [{ type: 'focused', selector: '[data-jini-part="confirm.cancel"]' }] },
+]);
+//# sourceMappingURL=scenarios.js.map

package/dist/toast.d.ts

@@ -0,0 +1,34 @@
+export interface ToastMessage {
+    readonly id: string;
+    readonly message: string;
+    readonly tone?: 'info' | 'success' | 'warning' | 'danger';
+    readonly durationMs?: number;
+}
+export interface ToastScheduler {
+    schedule(required: {
+        delayMs: number;
+        run: (required: Record<string, never>, optional?: Record<string, never>) => void;
+    }, optional?: Record<string, never>): unknown;
+    cancel(required: {
+        ticket: unknown;
+    }, optional?: Record<string, never>): void;
+}
+export interface ToastService {
+    push(required: Omit<ToastMessage, 'id'>, optional?: {
+        id?: string;
+    }): string;
+    dismiss(required: {
+        id: string;
+    }, optional?: Record<string, never>): void;
+    snapshot(required: Record<string, never>, optional?: Record<string, never>): readonly ToastMessage[];
+    subscribe(required: {
+        listener: (required: Record<string, never>, optional?: Record<string, never>) => void;
+    }, optional?: Record<string, never>): () => void;
+    dispose(required: Record<string, never>, optional?: Record<string, never>): void;
+}
+/** Instance-local queues avoid mixing messages between hosts and SSR requests. */
+export declare function createToastService(_required: Record<string, never>, optional?: {
+    scheduler?: ToastScheduler;
+    durationMs?: number;
+}): ToastService;
+//# sourceMappingURL=toast.d.ts.map

package/dist/toast.js

@@ -0,0 +1,52 @@
+const defaultScheduler = {
+    schedule: ({ delayMs, run }) => setTimeout(() => run({}), delayMs),
+    cancel: ({ ticket }) => clearTimeout(ticket),
+};
+/** Instance-local queues avoid mixing messages between hosts and SSR requests. */
+export function createToastService(_required, optional = {}) {
+    const scheduler = optional.scheduler ?? defaultScheduler;
+    let messages = Object.freeze([]), sequence = 0, disposed = false;
+    const listeners = new Set(), timers = new Map();
+    function emit() { for (const listener of listeners)
+        listener({}); }
+    function dismiss({ id }, _optional = {}) {
+        if (timers.has(id)) {
+            scheduler.cancel({ ticket: timers.get(id) });
+            timers.delete(id);
+        }
+        if (!messages.some(message => message.id === id))
+            return;
+        messages = Object.freeze(messages.filter(message => message.id !== id));
+        emit();
+    }
+    return Object.freeze({
+        push(input, opts = {}) {
+            if (disposed)
+                throw new Error('Toast service is disposed');
+            const id = opts.id ?? `toast-${++sequence}`;
+            dismiss({ id });
+            messages = Object.freeze([...messages, Object.freeze({ ...input, id })]);
+            emit();
+            const delayMs = input.durationMs ?? optional.durationMs ?? 5000;
+            if (delayMs > 0)
+                timers.set(id, scheduler.schedule({ delayMs, run: () => dismiss({ id }) }));
+            return id;
+        },
+        dismiss,
+        snapshot(_required, _optional = {}) { return messages; },
+        subscribe({ listener }, _optional = {}) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        dispose(_required, _optional = {}) {
+            disposed = true;
+            for (const ticket of timers.values())
+                scheduler.cancel({ ticket });
+            timers.clear();
+            messages = Object.freeze([]);
+            emit();
+            listeners.clear();
+        },
+    });
+}
+//# sourceMappingURL=toast.js.map

package/docs/decisions/DR-001.md

@@ -0,0 +1,32 @@
+# DR-001 — UI storefront with a framework-free contract
+
+Status: Accepted owner decision
+Date: 2026-10-03
+Contract: 1.0.0
+Package: @jini-ai/ui-kit 0.1.0
+
+## Inputs and problem
+
+The owner-approved Round 5 consensus and binding v1 decisions require reusable screens to request component roles from a host-selected kit. Importing UI primitives through an admin or feature package couples unrelated packages, and framework dependencies must not enter a headless or different-framework consumer.
+
+## Decision recorded
+
+Use one package with framework-free root contracts/rules and framework-specific subpaths. Root has no runtime dependencies. React, React DOM, and Vue are optional peers plus development dependencies. React v1 resolves 16 facade components through a provider with native defaults; partial overrides, extension, and a strict complete-kit variant serve different host needs. Every component can be replaced, including ConfirmDialog.
+
+Safety belongs to a framework-free controller with latest-policy reads and guarded actions. Confirmation views receive controller bags, never raw destructive callbacks. Cancel-first focus, pending dismissal blocking, human-only agent-handle withholding, and consequence labels are explicit contract obligations. Development mounted-DOM diagnostics default to native fallback and can be set to warn or off; fallback uses native actions too, because the original Button override may be the source of failure.
+
+Agent handles and metadata arrive through a host port. No agent-runtime package is imported. Context identity uses a shared global symbol for contract major 1, with a development warning on version skew. Opaque attrs target the actual documented focus target. Select keeps native semantics for a library-independent driver.
+
+Native styles are optional, layered, and keyed on parts. Toast state belongs to each service instance; the host mounts its ToastRegion. Browser-only conformance remains explicitly tagged and separate from jsdom evidence.
+
+## Consequences and deferred work
+
+Screen imports can remain stable as hosts replace component libraries. Hosts must implement the semantic contract, forward refs/attrs, and run conformance/browser validation. A development guard does not authorize destructive actions in production. Sharing a context does not remove the need for a compatible host React runtime.
+
+Planned spec entries have no stub component behavior. Vue/Angular subpaths, library adapters, motif loading, and consumer migrations are not implemented in v1. Migrate admin's provisional kit/confirmation first with direct imports and no forwarding shims; keep panel-kit logic separate. Follow with user-management, chat, and reusable UI features in separate jobs.
+
+## Delivery boundary
+
+This decision records supplied owner choices; it adds no architecture or security policy. Source/README/spec work is confined to ui-kit. Initial development used package-local dependency links because pgrep was unavailable, so no install step was run and this task left the lockfile unchanged. Executed test status belongs in the delivery report, not this decision record.
+
+Output: package boundary and customization rationale. Risk: custom adapters can satisfy types while violating mounted behavior. Suggested next assignee: consumer migration owner, then browser conformance owner.