@dsh-plugin/dsh-loader 1.1.0-dev.32287576957 → 1.2.0

package/lib/types/services/settings.d.ts

@@ -0,0 +1,47 @@
+import type { CordisContext, SettingsAPI, SettingsResult, NamespaceView } from '../types.js';
+/**
+ * Official browser-writable settings namespaces (dsh-host-apiproxy
+ * WEB_SETTINGS_NAMESPACES), as documented in dsh-upstream-fixes/README.md.
+ * Product namespaces and dynamic model-provider namespaces are not enumerable
+ * without dsh internals; callers may extend this set via `extraWhitelist`.
+ */
+export declare const DEFAULT_WEB_SETTINGS_NAMESPACES: Set<string>;
+/** A raw settings descriptor returned by the real settings service. */
+interface SettingsDescriptor {
+    ns: string;
+    schema: any;
+    value: any;
+    base?: any;
+    user?: any;
+    applies?: any;
+    secrets?: {
+        path: string[];
+        set?: any;
+    }[];
+    revision?: any;
+}
+/**
+ * Shape a raw settings descriptor into the official NamespaceView wire shape
+ * (mirrors dsh-upstream-fixes/lib/index.js `namespaceView`).
+ */
+export declare function toNamespaceView(descriptor: SettingsDescriptor): NamespaceView;
+/**
+ * Map a thrown settings error into a SettingsResult, preserving the official
+ * `settings-conflict` / `settings-rejected` classification.
+ */
+export declare function settingsErrorToResult(error: unknown, ns: string, method: string): SettingsResult;
+/**
+ * Build the `ctx.dshLoader.settings` stable API.
+ */
+export declare function createSettingsAPI(opts: {
+    ctx: CordisContext;
+    exposeAllNamespaces: boolean;
+    whitelist?: Set<string>;
+    /** The real `@deepseek-ai/dsh-settings` module, when it resolved at boot. */
+    module?: {
+        installSettingsSection?: (ctx: unknown, ns: unknown, schema: unknown, entry: unknown, hooks: unknown) => void;
+        settingsNamespace?: (id: string) => unknown;
+        SettingsConflictError?: new (...args: never[]) => Error;
+    };
+}): SettingsAPI;
+export {};

package/lib/types/types.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Shared TypeScript types for dshloader (host + client).
+ *
+ * These describe only the shapes dshloader itself relies on from the cordis
+ * runtime, the real dsh settings/web services, and the browser client
+ * environment. The real dsh services are intentionally typed loosely (`any`)
+ * because dshloader's whole job is to absorb dsh's internal shape changes
+ * behind a stable API — pinning them here would defeat the compatibility
+ * shim's purpose.
+ */
+/** Minimal cordis context surface dshloader uses. */
+export interface CordisContext {
+    get(name: string): any;
+    reflect: {
+        provide(name: string, value: any): void;
+    };
+    effect(fn: () => void | (() => void) | Promise<void | (() => void)>, label?: string): void;
+    /** Event registration; optional so a reduced context (tests) still type-checks. */
+    on?(event: string, listener: (...args: any[]) => any, options?: Record<string, unknown>): (() => void) | void;
+    /** Cordis logger; optional for the same reason. */
+    logger?: {
+        info?(...args: unknown[]): void;
+        warn?(...args: unknown[]): void;
+        error?(...args: unknown[]): void;
+    };
+}
+/** dshloader host adapter factory. */
+export interface AdapterFactory {
+    supports: string;
+    name: string;
+    create(ctx: CordisContext, config?: HostAdapterConfig): HostAdapter;
+}
+/** An instantiated host adapter. */
+export interface HostAdapter {
+    supports: string;
+    name: string;
+    apply?: () => Promise<void> | void;
+    dispose?: () => void;
+    /** Adapter-provided overrides for the stable API capabilities. */
+    settings?: any;
+    web?: any;
+    services?: any;
+    /** Optional override for the registry facade (it names private dsh shapes). */
+    registry?: any;
+}
+/** Config passed to an adapter's create(). */
+export interface HostAdapterConfig {
+    exposeAllNamespaces?: boolean;
+    hostPackageAliases?: Record<string, string>;
+}
+/** Result of AdapterRegistry.select(). */
+export interface AdapterSelection {
+    factory: AdapterFactory;
+    mode: 'exact' | 'range' | 'fallback';
+}
+/** dshloader host API exposed as `ctx.dshLoader`. */
+export interface HostAPI {
+    version: string;
+    dshVersion?: string;
+    adapterVersion?: string;
+    settings: SettingsAPI;
+    web: WebAPI;
+    services: ServicesAPI;
+    /** Monkey-patch protocol: RAW original, identity-checked restore, re-apply safe. */
+    patch: import('./patch.js').PatchAPI;
+    /** Stable facade over dsh registry internals (tools / sandbox / permission presets). */
+    registry: import('./services/registry.js').RegistryAPI;
+    /** Module-level LLM helpers that `services.get('llm')` cannot reach. */
+    llm: import('./services/llm.js').LlmAPI;
+    /** Module-level dsh symbols (defineTool, deadline, BasicCompactionEngine, ...). */
+    dsh: import('./services/dsh-symbols.js').DshSymbolsAPI;
+    registerPackageAlias(oldName: string, newName: string): void;
+}
+/** Settings stable API. */
+export interface SettingsAPI {
+    exposeAllNamespaces: boolean;
+    register(ns: string, schema: any, options?: any): any;
+    describe(options?: {
+        redactSecrets?: boolean;
+    }): any[];
+    update(ns: string, section?: any, expectedRevision?: number): Promise<SettingsResult>;
+    replace(ns: string, section?: any, expectedRevision?: number): Promise<SettingsResult>;
+    mutate(ns: string, ops?: any, expectedRevision?: number): Promise<SettingsResult>;
+    /**
+     * Build a settings namespace handle (delegates to dsh's `settingsNamespace`).
+     * @param id - namespace id; dsh accepts only `[a-z0-9-]`.
+     * @returns the namespace handle, or the raw id when the module is unavailable.
+     */
+    namespace(id: string): any;
+    /**
+     * Install the canonical optional-settings consumer wiring (delegates to dsh's
+     * `installSettingsSection`): register `ns` with `entry` as the `base` layer,
+     * point the hooks' source thunk at the resolved scope while a settings service
+     * exists, and fall back to `entry` when it goes away.
+     *
+     * Delegated rather than reimplemented — the fallback and fiber semantics are
+     * real upstream behaviour, not something a shim should copy.
+     *
+     * @returns `true` when the wiring was installed, `false` when dsh-settings is
+     *   unavailable (the caller then keeps using its composition entry).
+     */
+    installSection<T>(ctx: any, ns: any, schema: any, entry: T, hooks: {
+        setSource(current: () => T): void;
+        onChange(): void;
+        validate(value: T): void;
+    }): boolean;
+    /** Whether `error` is dsh's optimistic-concurrency `SettingsConflictError`. */
+    isConflictError(error: unknown): boolean;
+}
+/** Settings write result shape. */
+export interface SettingsResult {
+    ok: boolean;
+    value?: NamespaceView;
+    code?: string;
+    message?: string;
+    details?: Record<string, any>;
+}
+/** Official NamespaceView wire shape. */
+export interface NamespaceView {
+    ns: string;
+    schema: any;
+    value: any;
+    base?: any;
+    user?: any;
+    applies?: any;
+    secrets: {
+        path: string[];
+        set?: any;
+    }[];
+    revision?: any;
+}
+/** Web stable API. */
+export interface WebAPI {
+    /** Mount a handler on a path PREFIX (`kind: 'prefix'`), any method. */
+    register(prefix: string, handler: any): () => void;
+    /**
+     * Mount a handler on an EXACT path, any method (`kind: 'exact'`).
+     *
+     * Use this when one handler dispatches several methods itself — the shape
+     * dsh-network-settings' `/_dsh/.../settings` and `/_dsh/.../probe` routes use.
+     */
+    exact(path: string, handler: any): () => void;
+    get(path: string, handler: any): () => void;
+    post(path: string, handler: any): () => void;
+    put(path: string, handler: any): () => void;
+    patch(path: string, handler: any): () => void;
+    /** `DELETE` route. Named `del` because `delete` is awkward on a facade. */
+    del(path: string, handler: any): () => void;
+    use(middleware: any): () => void;
+    registerUpgrade(route: {
+        path: string;
+        handler: (req: any, socket: any, head: Buffer) => void;
+    }): () => void;
+}
+/** Services stable API. */
+export interface ServicesAPI {
+    get(name: string): any;
+    alias(from: string, to: string): void;
+}
+/** Selectable adapter entry exposed for CLI/tests. */
+export interface AdapterSelectionResult {
+    registry: import('./registry.js').AdapterRegistry;
+    factory: AdapterFactory;
+    mode: AdapterSelection['mode'];
+    dshVersion: string;
+}

package/lib/types/ui/anchors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The dsh-1-x SHELL ANCHOR TABLE.
+ *
+ * Every entry is a selector some plugin in this family currently hardcodes.
+ * Centralising them here is the whole point of `dshLoader.ui`: when dsh moves
+ * its DOM, this table changes and the plugins do not.
+ *
+ * Each anchor records WHO needed it and WHAT it was before, so a future
+ * maintainer can trace an anchor back to the behaviour it supports.
+ *
+ * @module @dsh-plugin/dsh-loader/ui/anchors
+ */
+import type { AnchorSpec } from './slots.js';
+/** Anchor names dshloader ships for the dsh 1.x shell. */
+export declare const ANCHOR_NAMES: readonly ['conversation.status', 'conversation.column', 'shell.overlay', 'desktop.detailsSurface', 'layout.frame', 'settings.nav'];
+/** One of the built-in anchor names. */
+export type BuiltinAnchor = (typeof ANCHOR_NAMES)[number];
+/**
+ * The built-in anchors for dsh 1.x (verified against dsh 0.1.0-rc.6).
+ *
+ * Provenance of each selector:
+ *
+ * - `conversation.status` — dsh-thought-buddy, `src/client/index.ts:632-637`:
+ *   `[data-conversation-scroll] [role="status"]` with a whole-document
+ *   `[role="status"]` fallback. Callers add their own `accept` (thought-buddy
+ *   matches the status text) via {@link AnchorSpec.accept} on a redefinition,
+ *   or filter in `MountSpec.when`.
+ * - `conversation.column` — dsh-better-sidebar, `src/client/Sidebar.tsx:396`:
+ *   `#root [data-slot="conversation"]`.
+ * - `shell.overlay` — dsh-code-review, `src/client.ts:1930` / `:2528`:
+ *   `[data-shell-overlay]`.
+ * - `desktop.detailsSurface` — dsh-code-review, `src/client.ts:1957`:
+ *   `.dshDesktopDetailsSurface`. A CSS-module-adjacent CLASS name and therefore
+ *   the most fragile anchor in the table; kept because the behaviour needs it.
+ * - `layout.frame` — dsh-code-review, `src/client.ts:1176` / `:1209` / `:1244`:
+ *   the frame whose `style.gridTemplateColumns` carries the sidebar width and
+ *   whose `data-sidebar-collapsed` attribute carries the collapsed state. This
+ *   anchor is READ (via `ui.hosts('layout.frame')`), never mounted into.
+ * - `settings.nav` — dsh-better-sidebar, `src/client/settings-nav-icon.ts`:
+ *   the settings navigation list that gets an icon synced into it.
+ */
+export declare const BUILTIN_ANCHORS: Record<BuiltinAnchor, AnchorSpec>;
+/** Read the sidebar layout state from the `layout.frame` anchor. */
+export interface LayoutFrameState {
+    /** Whether the shell reports the sidebar as collapsed. */
+    collapsed: boolean;
+    /** First `px` value of the frame's grid template, when present. */
+    firstColumnPx: number | undefined;
+}
+/**
+ * Project one `layout.frame` host into {@link LayoutFrameState}.
+ *
+ * Encapsulates the `style.gridTemplateColumns` parsing dsh-code-review does at
+ * `src/client.ts:1176`, so the regex lives with the anchor it belongs to.
+ */
+export declare function readLayoutFrame(host: Element): LayoutFrameState;

package/lib/types/ui/components.d.ts

@@ -0,0 +1,159 @@
+/**
+ * The dshloader BASE CONTROLS.
+ *
+ * A small, deliberately unopinionated control set so every plugin in this family
+ * renders the same design language instead of each hand-rolling inline styles
+ * (dsh-network-settings alone carries ~40 inline style objects today, and
+ * dsh-auxiliary / dsh-code-review each maintain their own button and input
+ * looks).
+ *
+ * Design rules:
+ *  - Styling is ONE injected stylesheet with `dshl-` prefixed classes, tagged
+ *    with the DSH `data-plugin` / `data-plugin-css` ownership attributes so HMR
+ *    can reclaim it. No CSS Modules, so consumers need no build-time CSS setup.
+ *  - Every colour is a DSH token with a fallback (see `./style.js`), so controls
+ *    follow the shell's theme, including dark mode, with no JS theme plumbing.
+ *  - Icons come from the curated set and inherit `currentColor`.
+ *  - Every control forwards native props and `className`, so a plugin can always
+ *    escape the defaults without forking the component.
+ *
+ * @module @dsh-plugin/dsh-loader/ui/components
+ */
+import * as React from 'react';
+import { type IconName } from './icons.js';
+/** Inject the control stylesheet once (idempotent, safe to call from any component). */
+export declare function ensureStyles(): void;
+/** Visual weight of a {@link Button}. */
+export type ButtonVariant = 'default' | 'primary' | 'ghost' | 'danger';
+/** {@link Button} props. */
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: ButtonVariant;
+    /** Compact height. */
+    small?: boolean;
+    /** Leading icon from the curated set. */
+    icon?: IconName;
+    /** Replace the label with a spinner and disable interaction. */
+    loading?: boolean;
+}
+/** A button in the DSH design language. */
+export declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+/** {@link IconButton} props. */
+export interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Icon from the curated set. */
+    icon: IconName;
+    /** Accessible name — required, since the button has no visible text. */
+    label: string;
+}
+/** A square icon-only button. `label` becomes its accessible name. */
+export declare const IconButton: React.ForwardRefExoticComponent<IconButtonProps & React.RefAttributes<HTMLButtonElement>>;
+/** {@link TextInput} props. */
+export interface TextInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+    /** Render with the monospace stack (paths, commands, tokens). */
+    mono?: boolean;
+    /** Mark the field as failing validation. */
+    invalid?: boolean;
+}
+/** A single-line text input. */
+export declare const TextInput: React.ForwardRefExoticComponent<TextInputProps & React.RefAttributes<HTMLInputElement>>;
+/** {@link Textarea} props. */
+export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
+    mono?: boolean;
+    invalid?: boolean;
+}
+/** A multi-line text area. */
+export declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
+/** One option of a {@link Select}. */
+export interface SelectOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+/** {@link Select} props. */
+export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, 'children'> {
+    options: readonly SelectOption[];
+    /** Optional leading placeholder rendered as a disabled empty option. */
+    placeholder?: string;
+}
+/**
+ * A dropdown built on the native `<select>`.
+ *
+ * Native on purpose: it inherits the platform's keyboard handling, mobile
+ * pickers, and accessibility for free. Plugins needing DSH's rich popup should
+ * use `Menu` from `@dsh-plugin/dsh-loader/ui-primitives` instead.
+ */
+export declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLSelectElement>>;
+/** {@link MenuSelect} props — a value dropdown rendered with the platform menu. */
+export interface MenuSelectProps {
+    options: readonly SelectOption[];
+    /** Currently selected value; renders {@link placeholder} when unmatched. */
+    value?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    /** Called with the chosen option's value. */
+    onChange?: (value: string) => void;
+    id?: string;
+    /** Field label, used for the trigger's accessible name. */
+    label?: string;
+    className?: string;
+}
+/**
+ * A dropdown whose trigger and popup match the shell's own pickers (the
+ * dsh-auxiliary model picker look): a bordered layer-1 trigger button plus the
+ * platform menu popup via {@link DshMenu}.
+ *
+ * Prefer this over {@link Select} on settings pages: the native `<select>`
+ * popup is OS-styled and cannot follow the shell theme, which is exactly the
+ * visual drift this component removes. `Select` remains for dense/inline forms
+ * where the native control's compactness matters.
+ */
+export declare function MenuSelect({ options, value, placeholder, disabled, onChange, id, label, className, }: MenuSelectProps): React.ReactElement;
+/** {@link Checkbox} props. */
+export interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type'> {
+    /** Text beside the box. */
+    label?: React.ReactNode;
+}
+/** A checkbox with an optional label. Native input styled via `accent-color`,
+ *  matching the shell's own settings pages. */
+export declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLInputElement>>;
+/** {@link Switch} props. */
+export interface SwitchProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type'> {
+    label?: React.ReactNode;
+}
+/** A toggle switch — use for "applies immediately" settings. */
+export declare const Switch: React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLInputElement>>;
+/** {@link Field} props. */
+export interface FieldProps {
+    label?: React.ReactNode;
+    /** Supporting description under the control. */
+    description?: React.ReactNode;
+    /** Validation message; renders in the danger colour. */
+    error?: React.ReactNode;
+    /** Associates the label with the control. */
+    htmlFor?: string;
+    children?: React.ReactNode;
+    className?: string;
+}
+/** Label + control + description/error, the standard settings row. */
+export declare function Field({ label, description, error, htmlFor, children, className }: FieldProps): React.ReactElement;
+/** {@link Card} props. */
+export interface CardProps {
+    title?: React.ReactNode;
+    children?: React.ReactNode;
+    className?: string;
+}
+/** A bordered section container — the settings-page card look. */
+export declare function Card({ title, children, className }: CardProps): React.ReactElement;
+/** A horizontal flex row with the standard gap. */
+export declare function Row({ children, className }: {
+    children?: React.ReactNode;
+    className?: string;
+}): React.ReactElement;
+/** A vertical flex column with the standard gap. */
+export declare function Col({ children, className }: {
+    children?: React.ReactNode;
+    className?: string;
+}): React.ReactElement;
+/** An inline spinner. */
+export declare function Spinner({ size }: {
+    size?: number;
+}): React.ReactElement;

package/lib/types/ui/icons.d.ts

@@ -0,0 +1,142 @@
+/**
+ * The curated dshloader ICON SET.
+ *
+ * Sourced from `@icon-park/react` so no plugin hand-maintains SVG path data
+ * again (dsh-better-sidebar's `src/client/icons.tsx` keeps 10 icons by hand
+ * today; every entry here replaces one of those or a
+ * `@deepseek-ai/dsh-client-ui-primitives` icon import).
+ *
+ * WHY A SUBSET, NOT `export *`: IconPark ships ~2000 icons. dshloader's client
+ * bundle is materialised through the DSH client module table, and a runtime
+ * module boundary cannot be tree-shaken — re-exporting everything would put all
+ * ~2000 icons into one bundle every plugin pays for. Naming a subset keeps the
+ * cost proportional (only the icons listed here are bundled), and a plugin that
+ * needs an exotic glyph can still depend on `@icon-park/react` directly.
+ *
+ * Adding an icon: import it below and add it to the export block. That is the
+ * only change needed — no SVG, no viewBox, no stroke bookkeeping.
+ *
+ * @module @dsh-plugin/dsh-loader/ui/icons
+ */
+import * as React from 'react';
+import { IconProvider, type IIconProps, type Theme } from '@icon-park/react/es/runtime';
+/** Props every dshloader icon accepts (IconPark's own prop contract). */
+export type IconProps = IIconProps;
+/** An icon component. */
+export type IconComponent = (props: IconProps) => React.ReactElement;
+/**
+ * The curated set, grouped by purpose. Names are intent-based (`Settings`,
+ * `Warning`) rather than IconPark's raw names so a glyph can be swapped without
+ * touching consumers.
+ */
+export declare const Icons: {
+    readonly ChevronUp: import("@icon-park/react/es/runtime").Icon;
+    readonly ChevronDown: import("@icon-park/react/es/runtime").Icon;
+    readonly ChevronLeft: import("@icon-park/react/es/runtime").Icon;
+    readonly ChevronRight: import("@icon-park/react/es/runtime").Icon;
+    readonly Back: import("@icon-park/react/es/runtime").Icon;
+    readonly Expand: import("@icon-park/react/es/runtime").Icon;
+    readonly More: import("@icon-park/react/es/runtime").Icon;
+    readonly Sort: import("@icon-park/react/es/runtime").Icon;
+    readonly Add: import("@icon-park/react/es/runtime").Icon;
+    readonly Edit: import("@icon-park/react/es/runtime").Icon;
+    readonly Write: import("@icon-park/react/es/runtime").Icon;
+    readonly Delete: import("@icon-park/react/es/runtime").Icon;
+    readonly Copy: import("@icon-park/react/es/runtime").Icon;
+    readonly Save: import("@icon-park/react/es/runtime").Icon;
+    readonly Search: import("@icon-park/react/es/runtime").Icon;
+    readonly Refresh: import("@icon-park/react/es/runtime").Icon;
+    readonly Download: import("@icon-park/react/es/runtime").Icon;
+    readonly Upload: import("@icon-park/react/es/runtime").Icon;
+    readonly Undo: import("@icon-park/react/es/runtime").Icon;
+    readonly Redo: import("@icon-park/react/es/runtime").Icon;
+    readonly Play: import("@icon-park/react/es/runtime").Icon;
+    readonly Stop: import("@icon-park/react/es/runtime").Icon;
+    readonly Close: import("@icon-park/react/es/runtime").Icon;
+    readonly CloseSmall: import("@icon-park/react/es/runtime").Icon;
+    readonly Check: import("@icon-park/react/es/runtime").Icon;
+    readonly CheckSmall: import("@icon-park/react/es/runtime").Icon;
+    readonly Info: import("@icon-park/react/es/runtime").Icon;
+    readonly Warning: import("@icon-park/react/es/runtime").Icon;
+    readonly Error: import("@icon-park/react/es/runtime").Icon;
+    readonly Success: import("@icon-park/react/es/runtime").Icon;
+    readonly Loading: import("@icon-park/react/es/runtime").Icon;
+    readonly Help: import("@icon-park/react/es/runtime").Icon;
+    readonly Settings: import("@icon-park/react/es/runtime").Icon;
+    readonly SettingsAlt: import("@icon-park/react/es/runtime").Icon;
+    readonly Config: import("@icon-park/react/es/runtime").Icon;
+    readonly Terminal: import("@icon-park/react/es/runtime").Icon;
+    readonly Code: import("@icon-park/react/es/runtime").Icon;
+    readonly FileCode: import("@icon-park/react/es/runtime").Icon;
+    readonly Doc: import("@icon-park/react/es/runtime").Icon;
+    readonly Folder: import("@icon-park/react/es/runtime").Icon;
+    readonly FolderOpen: import("@icon-park/react/es/runtime").Icon;
+    readonly GitBranch: import("@icon-park/react/es/runtime").Icon;
+    readonly Link: import("@icon-park/react/es/runtime").Icon;
+    readonly Web: import("@icon-park/react/es/runtime").Icon;
+    readonly Browser: import("@icon-park/react/es/runtime").Icon;
+    readonly Lock: import("@icon-park/react/es/runtime").Icon;
+    readonly Unlock: import("@icon-park/react/es/runtime").Icon;
+    readonly EyeOpen: import("@icon-park/react/es/runtime").Icon;
+    readonly EyeClosed: import("@icon-park/react/es/runtime").Icon;
+    readonly Alarm: import("@icon-park/react/es/runtime").Icon;
+    readonly Diamond: import("@icon-park/react/es/runtime").Icon;
+    readonly Apps: import("@icon-park/react/es/runtime").Icon;
+};
+/** Name of a curated icon. */
+export type IconName = keyof typeof Icons;
+/** Every curated icon name, for pickers and tests. */
+export declare const ICON_NAMES: IconName[];
+/**
+ * Look one icon up by name. Unknown names resolve to `Help` rather than
+ * throwing, so a stale name degrades to a visible placeholder.
+ */
+export declare function icon(name: IconName): IconComponent;
+/**
+ * `<Icon name="Settings" />` — the ergonomic form for data-driven icon choices
+ * (menu descriptors, settings rows) where a component reference is awkward.
+ */
+export declare function Icon({ name, ...rest }: {
+    name: IconName;
+} & IconProps): React.ReactElement;
+/** The icon defaults dshloader components render with. */
+export declare const DSH_ICON_CONFIG: {
+    strokeLinecap: import("@icon-park/react/es/runtime").StrokeLinecap;
+    strokeLinejoin: import("@icon-park/react/es/runtime").StrokeLinejoin;
+    prefix: string;
+    rtl: boolean;
+    size: number;
+    strokeWidth: number;
+    theme: Theme;
+    colors: {
+        filled: {
+            fill: string;
+            background: string;
+        };
+        twoTone: {
+            fill: string;
+            twoTone: string;
+        };
+        multiColor: {
+            outStrokeColor: string;
+            outFillColor: string;
+            innerStrokeColor: string;
+            innerFillColor: string;
+        };
+        outline: {
+            fill: string;
+            background: string;
+        };
+    };
+};
+/**
+ * Wrap a subtree so every dshloader icon inside inherits the DSH defaults
+ * (outline theme, `currentColor` fill, matching size). Plugins that render
+ * dshloader components inside their own React tree should mount this once near
+ * the root; the components in `./components.js` do not require it, but they look
+ * consistent with the rest of DSH when it is present.
+ */
+export declare function DshIconProvider({ children }: {
+    children?: React.ReactNode;
+}): React.ReactElement;
+export { IconProvider };

package/lib/types/ui/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The dshloader UI surface: virtual slots, the curated icon set, and the base
+ * controls, wrapped as one `ui` facade.
+ *
+ * Consumers reach this at runtime through `@dsh-plugin/dsh-loader/client`, which
+ * the DSH client module table resolves by stripping the `/client` suffix to
+ * dshloader's registered bundle id — so no alias and no load-order coordination
+ * is needed (see docs/ui.md).
+ *
+ * @module @dsh-plugin/dsh-loader/ui
+ */
+import { type LayoutFrameState } from './anchors.js';
+import { type CreateUiOptions, type UiAPI } from './slots.js';
+export * from './slots.js';
+export * from './anchors.js';
+export * from './style.js';
+export * from './icons.js';
+export * from './components.js';
+export * from './menu.js';
+/** The `ui` facade plus the built-in anchor helpers. */
+export interface DshLoaderUi extends UiAPI {
+    /** Read the shell's sidebar layout state, when the anchor resolves. */
+    layoutFrame(): LayoutFrameState | undefined;
+}
+/**
+ * Build the UI facade and seed it with the dsh 1.x anchor table.
+ *
+ * @param options - forwarded to {@link createUiAPI} (observe root, warn sink).
+ */
+export declare function createUi(options?: CreateUiOptions): DshLoaderUi;