@dxos/app-framework 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/dist/types/src/ui/components/PluginManager/PluginManagerContext.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginManagerContext.stories.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/PluginManager/PluginManagerContext.stories.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,KAAuC,MAAM,OAAO,CAAC;AAsK5D,QAAA,MAAM,IAAI;;;;;QAKN,MAAM;;CAEM,CAAC;eAEF,IAAI;AAEnB,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAC,OAAO,IAAI,CAAM,CAAC"}

package/dist/types/src/ui/components/PluginManager/PluginManagerProvider.d.ts

@@ -0,0 +1,10 @@
+import { type PluginManager } from '../../../core';
+/**
+ * Get the plugin manager.
+ */
+export declare const usePluginManager: () => PluginManager.PluginManager;
+/**
+ * Context provider for a plugin manager.
+ */
+export declare const PluginManagerProvider: import("react").Provider<PluginManager.PluginManager | undefined>;
+//# sourceMappingURL=PluginManagerProvider.d.ts.map

package/dist/types/src/ui/components/PluginManager/PluginManagerProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginManagerProvider.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/PluginManager/PluginManagerProvider.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD;;GAEG;AACH,eAAO,MAAM,gBAAgB,QAAO,aAAa,CAAC,aACoC,CAAC;AAEvF;;GAEG;AACH,eAAO,MAAM,qBAAqB,mEAAgC,CAAC"}

package/dist/types/src/ui/components/PluginManager/index.d.ts

@@ -0,0 +1,2 @@
+export * from './PluginManagerProvider';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/ui/components/PluginManager/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/PluginManager/index.ts"],"names":[],"mappings":"AAIA,cAAc,yBAAyB,CAAC"}

package/dist/types/src/ui/components/Surface/SurfaceComponent.d.ts

@@ -0,0 +1,24 @@
+import React, { type NamedExoticComponent, type RefAttributes } from 'react';
+import { type CapabilityManager } from '../../../core';
+import { type Props, type RoleToken, type TokenData, type TypedProps } from './types';
+/**
+ * A surface is a named region of the screen that can be populated by plugins.
+ */
+export declare const SurfaceComponent: (<TToken extends RoleToken<any>>(props: TypedProps<TToken> & RefAttributes<HTMLElement>) => React.ReactNode) & NamedExoticComponent<Props & RefAttributes<HTMLElement>>;
+/**
+ * @returns `true` if there is a contributed surface which matches the specified role & data, `false` otherwise.
+ *
+ * Two overloads:
+ * - Typed: pass a `type` role token and `data` is constrained to the token's
+ *   declared contract (e.g. `AppSurface.Section` requires `attendableId`).
+ * - Legacy: pass a string `role` and `data` is untyped.
+ */
+export declare function isSurfaceAvailable<TToken extends RoleToken<any>>(capabilityManager: CapabilityManager.CapabilityManager, args: {
+    type: TToken;
+    data?: TokenData<TToken>;
+    role?: never;
+}): boolean;
+export declare function isSurfaceAvailable(capabilityManager: CapabilityManager.CapabilityManager, args: Pick<Props, 'role' | 'data'> & {
+    type?: undefined;
+}): boolean;
+//# sourceMappingURL=SurfaceComponent.d.ts.map

package/dist/types/src/ui/components/Surface/SurfaceComponent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SurfaceComponent.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/Surface/SurfaceComponent.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,EAEZ,KAAK,oBAAoB,EAEzB,KAAK,aAAa,EAOnB,MAAM,OAAO,CAAC;AAQf,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAKvD,OAAO,EAEL,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,UAAU,EAEhB,MAAM,SAAS,CAAC;AAkJjB;;GAEG;AAEH,eAAO,MAAM,gBAAgB,EA6CxB,CAAC,CAAC,MAAM,SAAS,SAAS,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,WAAW,CAAC,KAAK,KAAK,CAAC,SAAS,CAAC,GAC/G,oBAAoB,CAAC,KAAK,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;AAwC3D;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,SAAS,SAAS,CAAC,GAAG,CAAC,EAC9D,iBAAiB,EAAE,iBAAiB,CAAC,iBAAiB,EACtD,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,GAC7D,OAAO,CAAC;AACX,wBAAgB,kBAAkB,CAChC,iBAAiB,EAAE,iBAAiB,CAAC,iBAAiB,EACtD,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,GACxD,OAAO,CAAC"}

package/dist/types/src/{components/App.stories.d.ts → ui/components/Surface/SurfaceComponent.stories.d.ts}

@@ -11,4 +11,4 @@ declare const meta: {
 export default meta;
 type Story = StoryObj<typeof meta>;
 export declare const Default: Story;
-//# sourceMappingURL=App.stories.d.ts.map
+//# sourceMappingURL=SurfaceComponent.stories.d.ts.map

package/dist/types/src/ui/components/Surface/SurfaceComponent.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SurfaceComponent.stories.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/Surface/SurfaceComponent.stories.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAA+D,MAAM,OAAO,CAAC;AA6HpF,QAAA,MAAM,IAAI;;;;;QAKN,MAAM;;CAE2B,CAAC;eAEvB,IAAI;AAEnB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnC,eAAO,MAAM,OAAO,EAAE,KAAU,CAAC"}

package/dist/types/src/ui/components/Surface/SurfaceInfo.d.ts

@@ -0,0 +1,11 @@
+import React, { type ReactElement, type Ref } from 'react';
+export type SurfaceInfoProps = {
+    children: ReactElement<{
+        ref?: Ref<HTMLElement>;
+    }>;
+};
+/**
+ * Debug wrapper for surfaces.
+ */
+export declare const SurfaceInfo: React.ForwardRefExoticComponent<SurfaceInfoProps & React.RefAttributes<HTMLElement>>;
+//# sourceMappingURL=SurfaceInfo.d.ts.map

package/dist/types/src/ui/components/Surface/SurfaceInfo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SurfaceInfo.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/Surface/SurfaceInfo.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,EACZ,KAAK,YAAY,EACjB,KAAK,GAAG,EAMT,MAAM,OAAO,CAAC;AAQf,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,YAAY,CAAC;QAAE,GAAG,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,CAAA;KAAE,CAAC,CAAC;CACpD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,sFA+EtB,CAAC"}

package/dist/types/src/ui/components/Surface/SurfaceProfilerContext.d.ts

@@ -0,0 +1,48 @@
+import React, { type PropsWithChildren, type ProfilerOnRenderCallback } from 'react';
+/**
+ * Single profiler record captured from React Profiler onRender callback.
+ */
+export type SurfaceProfilerEntry = {
+    id: string;
+    phase: 'mount' | 'update' | 'nested-update';
+    actualDuration: number;
+    baseDuration: number;
+    startTime: number;
+    commitTime: number;
+    timestamp: number;
+};
+/**
+ * Aggregated stats for a single profiled surface.
+ */
+export type SurfaceProfilerStats = {
+    id: string;
+    mountCount: number;
+    updateCount: number;
+    totalRenders: number;
+    avgActualDuration: number;
+    maxActualDuration: number;
+    avgBaseDuration: number;
+    lastActualDuration: number;
+    lastCommitTime: number;
+};
+/**
+ * Provider that collects React Profiler data from Surface components.
+ */
+export declare const SurfaceProfilerProvider: ({ children }: PropsWithChildren) => React.JSX.Element;
+/**
+ * Returns a stable onRender callback for use with React Profiler.
+ */
+export declare const useSurfaceProfilerCallback: () => ProfilerOnRenderCallback | undefined;
+/**
+ * Returns all profiler entries reactively.
+ */
+export declare const useSurfaceProfilerEntries: () => readonly SurfaceProfilerEntry[];
+/**
+ * Returns aggregated stats grouped by surface id.
+ */
+export declare const useSurfaceProfilerStats: () => SurfaceProfilerStats[];
+/**
+ * Clears all collected profiler entries.
+ */
+export declare const useSurfaceProfilerClear: () => (() => void) | undefined;
+//# sourceMappingURL=SurfaceProfilerContext.d.ts.map

package/dist/types/src/ui/components/Surface/SurfaceProfilerContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SurfaceProfilerContext.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/Surface/SurfaceProfilerContext.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,EAEZ,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAM9B,MAAM,OAAO,CAAC;AAIf;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,eAAe,CAAC;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAmEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,iBAAkB,iBAAiB,sBAQtE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,0BAA0B,QAAO,wBAAwB,GAAG,SAkBxE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,yBAAyB,QAAO,SAAS,oBAAoB,EAGzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,QAAO,oBAAoB,EAqC9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,QAAO,CAAC,MAAM,IAAI,CAAC,GAAG,SAGzD,CAAC"}

package/dist/types/src/ui/components/Surface/context.d.ts

@@ -0,0 +1,5 @@
+import { type Context } from 'react';
+import { type Props } from './types';
+export type SurfaceContext = Pick<Props, 'id' | 'role' | 'data'>;
+export declare const SurfaceContext: Context<SurfaceContext | undefined>;
+//# sourceMappingURL=context.d.ts.map

package/dist/types/src/ui/components/Surface/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/Surface/context.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,OAAO,EAAiB,MAAM,OAAO,CAAC;AAEpD,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;AAGjE,eAAO,MAAM,cAAc,EAAE,OAAO,CAAC,cAAc,GAAG,SAAS,CAAwD,CAAC"}

package/dist/types/src/ui/components/Surface/index.d.ts

@@ -0,0 +1,36 @@
+import { SurfaceContext } from './context';
+import { isSurfaceAvailable } from './SurfaceComponent';
+import { type Definition as SurfaceDefinition, type RoleToken as SurfaceRoleToken, type SurfaceBinding as SurfaceBindingType, type SurfaceFilter as SurfaceFilterType, type TokenData as SurfaceTokenData, type TypedProps as SurfaceTypedProps, create as createSurface, createWeb as createWebSurface } from './types';
+export declare namespace Surface {
+    type Definition = SurfaceDefinition;
+    const create: typeof createSurface;
+    const createWeb: typeof createWebSurface;
+    type Context = SurfaceContext;
+    const Context: import("react").Context<SurfaceContext | undefined>;
+    const Surface: (<TToken extends SurfaceRoleToken<any>>(props: SurfaceTypedProps<TToken> & import("react").RefAttributes<HTMLElement>) => React.ReactNode) & import("react").NamedExoticComponent<{
+        fallback?: import("react").FC<{
+            error: Error;
+            data?: any;
+        }>;
+        placeholder?: import("react").ReactNode;
+    } & Omit<import("./types").CoreProps<Record<string, unknown>>, "data" | "id" | "role"> & Partial<Pick<import("./types").CoreProps<Record<string, unknown>>, "data" | "id" | "role">> & {
+        type?: undefined;
+    } & {
+        [x: string]: any;
+    } & import("react").RefAttributes<HTMLElement>>;
+    const isAvailable: typeof isSurfaceAvailable;
+    type RoleToken<TData> = SurfaceRoleToken<TData>;
+    type Binding = SurfaceBindingType;
+    type Filter<TData> = SurfaceFilterType<TData>;
+    type TokenData<T> = SurfaceTokenData<T>;
+    type TypedProps<TToken extends SurfaceRoleToken<any>> = SurfaceTypedProps<TToken>;
+    const makeType: <TData>(role: string) => SurfaceRoleToken<TData>;
+    const isFilter: (value: unknown) => value is SurfaceFilterType<any>;
+    const ProfilerProvider: ({ children }: import("react").PropsWithChildren) => import("react").JSX.Element;
+    const useProfilerCallback: () => import("react").ProfilerOnRenderCallback | undefined;
+    const useProfilerEntries: () => readonly import("./SurfaceProfilerContext").SurfaceProfilerEntry[];
+    const useProfilerStats: () => import("./SurfaceProfilerContext").SurfaceProfilerStats[];
+    const useProfilerClear: () => (() => void) | undefined;
+}
+export type { SurfaceProfilerEntry, SurfaceProfilerStats } from './SurfaceProfilerContext';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/ui/components/Surface/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/Surface/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAoB,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAQ1E,OAAO,EACL,KAAK,UAAU,IAAI,iBAAiB,EACpC,KAAK,SAAS,IAAI,gBAAgB,EAClC,KAAK,cAAc,IAAI,kBAAkB,EACzC,KAAK,aAAa,IAAI,iBAAiB,EACvC,KAAK,SAAS,IAAI,gBAAgB,EAClC,KAAK,UAAU,IAAI,iBAAiB,EACpC,MAAM,IAAI,aAAa,EACvB,SAAS,IAAI,gBAAgB,EAG9B,MAAM,SAAS,CAAC;AAEjB,yBAAiB,OAAO,CAAC,CAAC;IACxB,KAAY,UAAU,GAAG,iBAAiB,CAAC;IACpC,MAAM,MAAM,sBAAgB,CAAC;IAC7B,MAAM,SAAS,yBAAmB,CAAC;IAE1C,KAAY,OAAO,GAAG,cAAc,CAAC;IAC9B,MAAM,OAAO,qDAAiB,CAAC;IAE/B,MAAM,OAAO;;;;;;;;;;mDAAmB,CAAC;IACjC,MAAM,WAAW,2BAAqB,CAAC;IAE9C,KAAY,SAAS,CAAC,KAAK,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACvD,KAAY,OAAO,GAAG,kBAAkB,CAAC;IACzC,KAAY,MAAM,CAAC,KAAK,IAAI,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACrD,KAAY,SAAS,CAAC,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC/C,KAAY,UAAU,CAAC,MAAM,SAAS,gBAAgB,CAAC,GAAG,CAAC,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAClF,MAAM,QAAQ,kDAAa,CAAC;IAC5B,MAAM,QAAQ,qDAAoB,CAAC;IAEnC,MAAM,gBAAgB,kFAA0B,CAAC;IACjD,MAAM,mBAAmB,4DAA6B,CAAC;IACvD,MAAM,kBAAkB,0EAA4B,CAAC;IACrD,MAAM,gBAAgB,iEAA0B,CAAC;IACjD,MAAM,gBAAgB,gCAA0B,CAAC;CACzD;AAED,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/types/src/ui/components/Surface/types.d.ts

@@ -0,0 +1,197 @@
+import type { FC, PropsWithChildren, ReactNode, RefCallback } from 'react';
+import type { MakeOptional, Position } from '@dxos/util';
+/**
+ * A typed role token. Carries a role string for runtime dispatch plus a phantom
+ * data type so consumers using `type={SomeToken}` and providers using
+ * `AppSurface.object(SomeToken, ...)` share a single type-level contract.
+ *
+ * Mint via {@link makeType}.
+ */
+export type RoleToken<TData> = {
+    readonly role: string;
+    /** Covariant phantom; never accessed at runtime. */
+    readonly _phantom?: TData;
+};
+/**
+ * One entry in a {@link SurfaceFilter} — a role plus the guard that validates
+ * the data shape when the Surface dispatcher is matching that role.
+ */
+export type SurfaceBinding = {
+    readonly role: string;
+    readonly guard: (data: unknown) => boolean;
+};
+/**
+ * Typed filter binding for {@link create}. Combines one or more `(role, guard)`
+ * pairs so a provider can register against multiple roles while keeping the
+ * role and its data shape in a single expression.
+ */
+export type SurfaceFilter<TData> = {
+    readonly bindings: ReadonlyArray<SurfaceBinding>;
+    /** Covariant phantom; never accessed at runtime. */
+    readonly _phantom?: TData;
+};
+/**
+ * Narrow data type carried by a role token.
+ */
+export type TokenData<T> = T extends RoleToken<infer D> ? D : never;
+/**
+ * Runtime guard for {@link SurfaceFilter}. Distinguishes new-style filter
+ * bindings from legacy predicate filters.
+ */
+export declare const isSurfaceFilter: (value: unknown) => value is SurfaceFilter<any>;
+/**
+ * Mints a typed role token. Identity is structural; all tokens with the same
+ * `role` string are interchangeable at runtime.
+ */
+export declare const makeType: <TData>(role: string) => RoleToken<TData>;
+/**
+ * Props that are passed to the Surface component.
+ *
+ * The role can be provided either as a string via `role` or as a typed
+ * {@link RoleToken} via `type`. The typed form narrows `data` to the token's
+ * declared shape.
+ */
+export type Props<T extends Record<string, any> = Record<string, unknown>> = {
+    /**
+     * If specified, the Surface will be wrapped in an error boundary.
+     * The fallback component will be rendered if an error occurs.
+     */
+    fallback?: FC<{
+        error: Error;
+        data?: any;
+    }>;
+    /**
+     * If specified, the Surface will be wrapped in a suspense boundary.
+     * The placeholder component will be rendered while the surface component is loading.
+     */
+    placeholder?: ReactNode;
+} & MakeOptional<CoreProps<T>, 'id' | 'data' | 'role'> & {
+    /**
+     * Explicitly disallow `type` on the untyped Props overload — if the caller
+     * provides `type={AppSurface.X}`, TypeScript must route to the typed
+     * overload (where `data` is narrowed by the token). Without this, the
+     * catch-all index signature below would accept any `type` value and mask
+     * the typed overload entirely.
+     */
+    type?: undefined;
+} /**
+ * Additional props to pass to the component.
+ * These props are not used by Surface itself but may be used by components which resolve the surface.
+ * Exclude known prop names to prevent overriding well-defined props.
+ */ & {
+    [K in keyof Record<string, any>]: K extends keyof CoreProps<T> | 'fallback' | 'placeholder' | 'type' ? never : any;
+};
+/**
+ * Typed Surface consumer props — carries the role/data-shape contract via a
+ * {@link RoleToken}. Available as a typed overload of the Surface component so
+ * ad-hoc `type` fields on arbitrary spread props don't conflict with the
+ * untyped consumer form.
+ */
+export type TypedProps<TToken extends RoleToken<any>> = {
+    fallback?: FC<{
+        error: Error;
+        data?: any;
+    }>;
+    placeholder?: ReactNode;
+    id?: string;
+    type: TToken;
+    data?: TokenData<TToken>;
+    limit?: number | undefined;
+} & {
+    [K in keyof Record<string, any>]: K extends 'fallback' | 'placeholder' | 'id' | 'type' | 'data' | 'limit' ? never : any;
+};
+/**
+ * NOTE: If `[key: string]: unknown` is included in shared types, when re-used other fields become unknown as well.
+ */
+export type CoreProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
+    /**
+     * ID for debugging.
+     */
+    id: string;
+    /**
+     * Role defines how the data should be rendered. For new code, prefer the
+     * typed overload of the Surface component which takes a {@link RoleToken}
+     * via the `type` prop instead — it enforces a role/data contract at compile
+     * time.
+     */
+    role: string;
+    /**
+     * The data to be rendered by the surface.
+     * NOTE: This must be a stable value.
+     */
+    data: T;
+    /**
+     * If more than one component is resolved, the limit determines how many are rendered.
+     */
+    limit?: number | undefined;
+}>;
+export type ComponentProps<T extends Record<string, any> = Record<string, any>> = CoreProps<T> & {
+    ref?: RefCallback<HTMLElement>;
+} & Record<string, any>;
+/**
+ * React component used to render a surface once is has matched.
+ */
+export type ComponentFunction<T extends Record<string, any> = Record<string, any>> = (props: ComponentProps<T>) => ReactNode;
+/**
+ * Definition of when a React component surface should be rendered.
+ *
+ * The optional `filter` receives the consumer-supplied `role` as its second
+ * argument so a single definition can encode role-specific guards (used by the
+ * {@link SurfaceFilter}-based `create` overload).
+ */
+export type ReactDefinition<T extends Record<string, any> = any> = Readonly<{
+    kind: 'react';
+    id: string;
+    role: string | string[];
+    position?: Position;
+    component: ComponentFunction<T>;
+    filter?: (data: Record<string, unknown>, role?: string) => data is T;
+}>;
+/**
+ * Definition of when a Web Component surface should be rendered.
+ */
+export type WebComponentDefinition<T extends Record<string, any> = any> = Readonly<{
+    kind: 'web-component';
+    id: string;
+    role: string | string[];
+    position?: Position;
+    /**
+     * The tag name of the Web Component to render.
+     * The Web Component will receive the same props as React surfaces via properties/attributes.
+     */
+    tagName: string;
+    filter?: (data: Record<string, unknown>, role?: string) => data is T;
+}>;
+/**
+ * Definition of when a surface (React or Web Component) should be rendered.
+ */
+export type Definition<T extends Record<string, any> = any> = ReactDefinition<T> | WebComponentDefinition<T>;
+/**
+ * Typed React surface definition — role is derived from the filter's bindings.
+ */
+export type TypedReactDefinition<T extends Record<string, any> = any> = Readonly<{
+    id: string;
+    filter: SurfaceFilter<T>;
+    component: ComponentFunction<T>;
+    position?: Position;
+}>;
+/**
+ * Typed Web Component surface definition.
+ */
+export type TypedWebComponentDefinition<T extends Record<string, any> = any> = Readonly<{
+    id: string;
+    filter: SurfaceFilter<T>;
+    tagName: string;
+    position?: Position;
+}>;
+/**
+ * Creates a React surface definition.
+ */
+export declare function create<T extends Record<string, any> = any>(definition: TypedReactDefinition<T>): ReactDefinition<T>;
+export declare function create<T extends Record<string, any> = any>(definition: Omit<ReactDefinition<T>, 'kind'>): ReactDefinition<T>;
+/**
+ * Creates a Web Component surface definition.
+ */
+export declare function createWeb<T extends Record<string, any> = any>(definition: TypedWebComponentDefinition<T>): WebComponentDefinition<T>;
+export declare function createWeb<T extends Record<string, any> = any>(definition: Omit<WebComponentDefinition<T>, 'kind'>): WebComponentDefinition<T>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types/src/ui/components/Surface/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/Surface/types.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,EAAE,EAAE,iBAAiB,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAE3E,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,KAAK,IAAI;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CAC5C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,KAAK,IAAI;IACjC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IACjD,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,eAAe,UAAW,OAAO,KAAG,KAAK,IAAI,aAAa,CAAC,GAAG,CAC+B,CAAC;AAE3G;;;GAGG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,QAAQ,MAAM,KAAG,SAAS,CAAC,KAAK,CAAe,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAC3E;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,CAAC;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAE5C;;;OAGG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC,GAAG;IACrD;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,CAAC;;;;GAIC,GAAG;KACH,CAAC,IAAI,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,SAAS,MAAM,SAAS,CAAC,CAAC,CAAC,GAAG,UAAU,GAAG,aAAa,GAAG,MAAM,GAAG,KAAK,GAAG,GAAG;CACnH,CAAC;AAEJ;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,MAAM,SAAS,SAAS,CAAC,GAAG,CAAC,IAAI;IACtD,QAAQ,CAAC,EAAE,EAAE,CAAC;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,GAAG;KAKD,CAAC,IAAI,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,SAAS,UAAU,GAAG,aAAa,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GACrG,KAAK,GACL,GAAG;CACR,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,iBAAiB,CAAC;IACjG;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,IAAI,EAAE,CAAC,CAAC;IAER;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,CAAC,CAAC;AAGH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG;IAC/F,GAAG,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;CAChC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CACnF,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,KACrB,SAAS,CAAC;AAEf;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,IAAI,QAAQ,CAAC;IAC1E,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC;CACtE,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,IAAI,QAAQ,CAAC;IACjF,IAAI,EAAE,eAAe,CAAC;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC;CACtE,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,IAAI,eAAe,CAAC,CAAC,CAAC,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAAC;AAE7G;;GAEG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,IAAI,QAAQ,CAAC;IAC/E,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACzB,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAChC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,2BAA2B,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,IAAI,QAAQ,CAAC;IACtF,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,CAAC,CAAC;AAkBH;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,UAAU,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;AACrH,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EACxD,UAAU,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,GAC3C,eAAe,CAAC,CAAC,CAAC,CAAC;AAYtB;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EAC3D,UAAU,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACzC,sBAAsB,CAAC,CAAC,CAAC,CAAC;AAC7B,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EAC3D,UAAU,EAAE,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,GAClD,sBAAsB,CAAC,CAAC,CAAC,CAAC"}

package/dist/types/src/ui/components/Surface/types.test.d.ts

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

package/dist/types/src/ui/components/Surface/types.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.test.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/Surface/types.test.ts"],"names":[],"mappings":""}

package/dist/types/src/ui/components/index.d.ts

@@ -0,0 +1,5 @@
+export * from './App';
+export * from './Placeholder';
+export * from './PluginManager';
+export * from './Surface';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/ui/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/ui/components/index.ts"],"names":[],"mappings":"AAIA,cAAc,OAAO,CAAC;AACtB,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC"}

package/dist/types/src/ui/hooks/index.d.ts

@@ -0,0 +1,6 @@
+export * from './useApp';
+export * from './useCapabilities';
+export * from './useLoading';
+export * from './useSettingsState';
+export * from './useSurface';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/ui/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/index.ts"],"names":[],"mappings":"AAIA,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC"}

package/dist/types/src/ui/hooks/useApp.d.ts

@@ -0,0 +1,88 @@
+import React, { type FC } from 'react';
+import { type FallbackProps } from '@dxos/react-error-boundary';
+import { type ActivationEvent, type Plugin, PluginManager } from '../../core';
+export type StartupProgress = {
+    /** Number of modules that have been activated. */
+    activated: number;
+    /** Total number of modules registered. */
+    total: number;
+    /** Fractional progress (0-1). */
+    progress: number;
+    /**
+     * Raw activation event key (e.g. `org.dxos.app-framework.event.startup`).
+     * Set on event-level transitions, *and* on module-level transitions where
+     * it carries the parent activation event that first triggered the
+     * module's load (plumbed through `_loadCapabilitiesForModules` →
+     * `_loadModule`). Consumers can use this either as the primary id (when
+     * {@link module} is absent) or as an extra "context" field alongside
+     * {@link module}.
+     */
+    event?: string;
+    /**
+     * Raw module id (e.g. `org.dxos.plugin.observability.module.ReactSurface`)
+     * when the in-flight activation is module-level. When present,
+     * {@link event} may also be set, identifying the parent activation that
+     * triggered this module's load.
+     */
+    module?: string;
+    /**
+     * Pre-humanized label for the currently surfaced transition (module
+     * label if {@link module} is set, otherwise the event label), supplied
+     * for consumers that want a sensible default. Hosts that prefer to
+     * render their own label can read the raw {@link event}/{@link module}
+     * fields and ignore this — the framework leaves the policy choice
+     * (which transitions to surface, how to format them, whether to drop
+     * sub-modules entirely) to the host's `Placeholder`.
+     */
+    humanizedName?: string;
+};
+export type PlaceholderProps = {
+    stage?: number;
+    progress?: StartupProgress;
+};
+export type UseAppOptions = {
+    pluginManager?: PluginManager.PluginManager;
+    pluginLoader?: PluginManager.ManagerOptions['pluginLoader'];
+    onPluginRemove?: PluginManager.ManagerOptions['onRemove'];
+    plugins?: Plugin.Plugin[];
+    core?: string[];
+    defaults?: string[];
+    /**
+     * Additional activation events to fire before startup.
+     * These are fired alongside SetupReactSurface before the Startup event.
+     */
+    setupEvents?: ActivationEvent.ActivationEvent[];
+    cacheEnabled?: boolean;
+    safeMode?: boolean;
+    debounce?: number;
+    timeout?: number;
+    fallback?: FC<FallbackProps>;
+    placeholder?: FC<PlaceholderProps>;
+};
+/**
+ * Expected usage is for this to be the entrypoint of the application.
+ * Initializes plugins and renders the root components.
+ *
+ * @example
+ * const plugins = [LayoutPlugin(), MyPlugin()];
+ * const core = [LayoutPluginId];
+ * const default = [MyPluginId];
+ * const fallback = <div>Initializing Plugins...</div>;
+ * const App = useApp({ plugins, core, default, fallback });
+ * createRoot(document.getElementById('root')!).render(
+ *   <StrictMode>
+ *     <App />
+ *   </StrictMode>,
+ * );
+ *
+ * @param params.pluginLoader A function which loads new plugins.
+ * @param params.plugins All plugins available to the application.
+ * @param params.core Core plugins which will always be enabled.
+ * @param params.defaults Default plugins are enabled by default but can be disabled by the user.
+ * @param params.cacheEnabled Whether to cache enabled plugins in localStorage.
+ * @param params.safeMode Whether to enable safe mode, which disables optional plugins.
+ * @param params.fallback Fallback component to render if an error occurs during startup.
+ * @param params.placeholder Placeholder component to render during startup.
+ */
+export declare const useApp: ({ pluginManager, pluginLoader: pluginLoaderProp, onPluginRemove, plugins: pluginsProp, core: coreProp, defaults: defaultsProp, setupEvents: setupEventsProp, placeholder, fallback, cacheEnabled, safeMode, debounce, timeout, }: UseAppOptions) => () => React.JSX.Element;
+//# sourceMappingURL=useApp.d.ts.map

package/dist/types/src/ui/hooks/useApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useApp.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useApp.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,EAAE,KAAK,EAAE,EAAqD,MAAM,OAAO,CAAC;AAK1F,OAAO,EAAgC,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAM9F,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,MAAM,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAK9E,MAAM,MAAM,eAAe,GAAG;IAC5B,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,aAAa,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC;IAC5C,YAAY,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;IAC5D,cAAc,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC,eAAe,EAAE,CAAC;IAChD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC;IAC7B,WAAW,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC;CACpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,MAAM,qOAchB,aAAa,4BAyNf,CAAC"}

package/dist/types/src/ui/hooks/useApp.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=useApp.test.d.ts.map

package/dist/types/src/ui/hooks/useApp.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useApp.test.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useApp.test.tsx"],"names":[],"mappings":""}

package/dist/types/src/ui/hooks/useCapabilities.d.ts

@@ -0,0 +1,31 @@
+import { type Atom } from '@effect-atom/atom-react';
+import { Capabilities } from '../../common';
+import { type Capability } from '../../core';
+/**
+ * Hook to request capabilities from the plugin context.
+ * @returns An array of capabilities.
+ */
+export declare const useCapabilities: <T>(interfaceDef: Capability.InterfaceDef<T>) => T[];
+/**
+ * Hook to request a capability from the plugin context.
+ * @returns The capability.
+ * @throws If no capability is found.
+ */
+export declare const useCapability: <T>(interfaceDef: Capability.InterfaceDef<T>) => T;
+/**
+ * Hook to get the current value of an atom capability.
+ * Automatically subscribes to changes.
+ * @example const settings = useAtomCapability(ThreadCapabilities.Settings);
+ */
+export declare const useAtomCapability: <T>(atomCapability: Capability.InterfaceDef<Atom.Atom<T>>) => T;
+/**
+ * Hook to get value and updater for an atom capability.
+ * Returns [currentValue, updateFn] similar to useState.
+ * @example const [settings, updateSettings] = useAtomCapabilityState(ThreadCapabilities.Settings);
+ */
+export declare const useAtomCapabilityState: <T>(atomCapability: Capability.InterfaceDef<Atom.Writable<T>>) => [T, (fn: (current: T) => T) => void];
+/**
+ * Hook to get the operation invoker capability.
+ */
+export declare const useOperationInvoker: () => Capabilities.OperationInvoker;
+//# sourceMappingURL=useCapabilities.d.ts.map

package/dist/types/src/ui/hooks/useCapabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCapabilities.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useCapabilities.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,IAAI,EAAgB,MAAM,yBAAyB,CAAC;AAKlE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,gBAAgB,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,QAG1E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,gBAAgB,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,MAIxE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,kBAAkB,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAG,CAG5F,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,CAAC,kBACtB,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KACxD,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAWrC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,QAAO,YAAY,CAAC,gBAAgE,CAAC"}

package/dist/types/src/{components → ui/hooks}/useLoading.d.ts

@@ -1,4 +1,3 @@
-import { type AppProps } from './App';
 export declare enum LoadingState {
     Loading = 0,
     FadeIn = 1,
@@ -15,5 +14,5 @@ export declare enum LoadingState {
  * 2: Fade-out  - Fade out the loading animation.
  * 3: Done      - Remove the placeholder.
  */
-export declare const useLoading: (state: AppProps["state"], debounce?: number) => LoadingState;
+export declare const useLoading: (ready: boolean, debounce?: number) => LoadingState;
 //# sourceMappingURL=useLoading.d.ts.map

package/dist/types/src/ui/hooks/useLoading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLoading.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useLoading.tsx"],"names":[],"mappings":"AAMA,oBAAY,YAAY;IACtB,OAAO,IAAI;IACX,MAAM,IAAI;IACV,OAAO,IAAI;IACX,IAAI,IAAI;CACT;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,UAAW,OAAO,oCAoDxC,CAAC"}

package/dist/types/src/ui/hooks/useSettingsState.d.ts

@@ -0,0 +1,10 @@
+import { type Atom } from '@effect-atom/atom-react';
+/**
+ * Hook to read and update a settings atom.
+ * Returns the current value and an update function.
+ */
+export declare const useSettingsState: <T>(atom: Atom.Writable<T>) => {
+    settings: T;
+    updateSettings: (fn: (current: T) => T) => void;
+};
+//# sourceMappingURL=useSettingsState.d.ts.map

package/dist/types/src/ui/hooks/useSettingsState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSettingsState.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useSettingsState.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,IAAI,EAAiC,MAAM,yBAAyB,CAAC;AAGnF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,QAC1B,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,KACrB;IAAE,QAAQ,EAAE,CAAC,CAAC;IAAC,cAAc,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAAA;CAYhE,CAAC"}

package/dist/types/src/ui/hooks/useSurface.d.ts

@@ -0,0 +1,3 @@
+import { Surface } from '../components';
+export declare const useSurface: () => Surface.Context;
+//# sourceMappingURL=useSurface.d.ts.map

package/dist/types/src/ui/hooks/useSurface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSurface.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useSurface.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,eAAO,MAAM,UAAU,QAAO,OAAO,CAAC,OAErC,CAAC"}

package/dist/types/src/ui/index.d.ts

@@ -0,0 +1,3 @@
+export * from './components';
+export * from './hooks';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/ui/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ui/index.ts"],"names":[],"mappings":"AAIA,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC"}