@qilin-agent/client-ui-session 0.0.0-stage → 3.1.3

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region lib/types/index.js
+/** Host loader entry for the browser-only Session UI adapter. */
+/** Provides no Host-side behavior. */
+function apply() {}
+//#endregion
+export { apply };

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

@@ -0,0 +1,192 @@
+/** Session Controller adapter for React selector hooks and Slot scope data. */
+import { Service, type Context } from '@qilin-agent/kylin';
+import type { ISessions, SessionBinding, SessionListState, SessionReference, SessionRetainInfo, SessionSnapshot, UseProjection } from '@qilin-agent/api-session-controller/client';
+import type { SessionId } from '@qilin-agent/session/types';
+import type { HostObservable, KeyedStandardSource, MaybeSnapshotSelectorHook, SlotScopeAdapter, SnapshotSelectorHook, StandardSourceBinding } from '@qilin-agent/client-ui-slots';
+/** Selector hook over the Session Controller list and current selection. */
+export type UseSessions = SnapshotSelectorHook<SessionListState>;
+/** Selector hook over one Session's lifecycle and control state. */
+export type SessionSnapshotSelector = SnapshotSelectorHook<SessionSnapshot>;
+/** Public name for the Session lifecycle selector hook. */
+export type UseSession = SessionSnapshotSelector;
+/** Common identity carried by every Session-scoped pending interaction. */
+export interface SessionPendingInteractionBase {
+    /** Opaque request identity; a replacement request must use a new key. */
+    readonly key: string;
+    /** Domain-owned presentation discriminator. */
+    readonly kind: string;
+    /** Session whose UI can answer this interaction. */
+    readonly sessionId: SessionId;
+}
+/** Declaration-merged map of domain keys to their pending-interaction values. */
+export interface SessionPendingInteractionMap {
+}
+/** Union of every pending-interaction value contributed by the assembled Client. */
+export type SessionPendingInteraction = [
+    keyof SessionPendingInteractionMap
+] extends [never] ? SessionPendingInteractionBase : SessionPendingInteractionMap[keyof SessionPendingInteractionMap];
+/** Independent UI status facts for one Session identity. */
+export interface SessionStatus {
+    /** Latest known running state; absent until a baseline or event establishes it. */
+    readonly running: boolean | undefined;
+    /** Highest-precedence domain request currently awaiting user interaction. */
+    readonly pendingInteraction: SessionPendingInteraction | undefined;
+    /** Whether an observed stop outside the main view still needs acknowledgement. */
+    readonly completionUnread: boolean;
+}
+/** Current UI status indexed by Session identity. */
+export type SessionStatusSnapshot = ReadonlyMap<SessionId, SessionStatus>;
+/** Selector hook over the unified Session UI status snapshot. */
+export type UseSessionStatus = SnapshotSelectorHook<SessionStatusSnapshot>;
+/** Selector hook for explicit or surrounding-Provider Session reference counts. */
+export interface UseSessionRetainInfo {
+    /**
+     * Read the complete retain information for an explicit Session identity.
+     * @param sessionId - Session identity to inspect without retaining it.
+     * @returns current local reference counts, or absence while the source is unavailable.
+     */
+    (sessionId: SessionId): SessionRetainInfo | undefined;
+    /**
+     * Select from the retain information for an explicit Session identity.
+     * @param sessionId - Session identity to inspect without retaining it.
+     * @param selector - projection over the current value.
+     * @param equal - optional selected-value equality.
+     * @returns selected value.
+     */
+    <Selected>(sessionId: SessionId, selector: (value: SessionRetainInfo | undefined) => Selected, equal?: (left: Selected, right: Selected) => boolean): Selected;
+    /**
+     * Select from the surrounding Provider's Session retain information.
+     * @param selector - projection receiving absence outside a Session binding.
+     * @param equal - optional selected-value equality.
+     * @returns selected value.
+     */
+    <Selected>(selector: (value: SessionRetainInfo | undefined) => Selected, equal?: (left: Selected, right: Selected) => boolean): Selected;
+}
+/** Publish one pending interaction and define how plugin teardown delegates it. */
+export type PendingInteractionPublisher<T extends SessionPendingInteractionBase> = (interaction: T, delegate: () => Promise<void>) => () => void;
+declare module '@qilin-agent/client-ui-slots' {
+    interface SlotScopeTargetMap {
+        session: SessionReference;
+    }
+    interface GlobalStandardProps {
+        /** Session list and current selection. */
+        useSessions: UseSessions;
+        useSessionStatus: UseSessionStatus;
+        useSessionRetainInfo: UseSessionRetainInfo;
+    }
+    interface SessionStandardProps {
+        /** Current Session lifecycle and control state. */
+        useSession: SessionSnapshotSelector;
+        /** Current Session identity. */
+        sessionId: SessionId;
+        /** Host-computed projection values addressed by projection key. */
+        useProjection: UseProjection;
+    }
+    interface SessionMaybeStandardProps {
+        /** Current Session state, absent while no Session is selected. */
+        useSession: MaybeSnapshotSelectorHook<SessionSnapshot>;
+        /** Current Session identity, absent while no Session is selected. */
+        sessionId: SessionId | undefined;
+        /** Host-computed projection values; every key is absent without a Session. */
+        useProjection: UseProjection;
+    }
+}
+declare module '@qilin-agent/api-session-controller/client' {
+    interface SessionReferenceSourceMap {
+        mainView: unknown;
+    }
+}
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        /** Session Controller adapter and session-scoped source registry. */
+        uiSession: UiSession;
+    }
+}
+type SessionSourceRoster = readonly string[] | undefined;
+type SessionSourceRecord<Roster extends SessionSourceRoster, Value> = Roster extends readonly string[] ? Readonly<Record<Roster[number], Value>> : never;
+/** Bare values produced by one Session-scoped source contribution. */
+export interface SessionSourceContribution<Hooks extends SessionSourceRoster = SessionSourceRoster, KeyedHooks extends SessionSourceRoster = SessionSourceRoster, Props extends SessionSourceRoster = SessionSourceRoster> {
+    readonly hooks?: SessionSourceRecord<Hooks, HostObservable<unknown>>;
+    readonly keyedHooks?: SessionSourceRecord<KeyedHooks, KeyedStandardSource>;
+    readonly props?: SessionSourceRecord<Props, unknown>;
+}
+/** Static roster and per-Session resolver for one standard-props contribution. */
+export interface SessionSourceDescriptor<Hooks extends SessionSourceRoster = SessionSourceRoster, KeyedHooks extends SessionSourceRoster = SessionSourceRoster, Props extends SessionSourceRoster = SessionSourceRoster> {
+    readonly hooks?: Hooks;
+    readonly keyedHooks?: KeyedHooks;
+    readonly props?: Props;
+    /**
+     * Resolve every declared member for one Session binding.
+     * @param binding - Controller-owned Session binding.
+     * @returns all declared bare sources and stable props.
+     */
+    resolve(binding: SessionBinding): SessionSourceContribution<NoInfer<Hooks>, NoInfer<KeyedHooks>, NoInfer<Props>>;
+}
+/** Session-scoped source roster and renderer adapter. */
+export declare class UiSession extends Service {
+    private readonly sessions;
+    private readonly descriptors;
+    private readonly bindings;
+    private readonly absent;
+    private readonly current;
+    private readonly pendingDomains;
+    private pendingSnapshot;
+    private readonly running;
+    private readonly completionUnread;
+    private statusSnapshot;
+    private readonly statusListeners;
+    private mainRetainId;
+    private disposeMainRetain;
+    private active;
+    /** Root source combining running, pending-interaction, and completion-reminder facts. */
+    readonly sessionStatus: HostObservable<SessionStatusSnapshot>;
+    /** Renderer-facing adapter for `session` and `session-maybe` scopes. */
+    readonly adapter: SlotScopeAdapter;
+    /**
+     * @param ctx - Client root context.
+     * @param sessions - Controller-owned Session object layer.
+     */
+    constructor(ctx: Context, sessions: ISessions);
+    /**
+     * Resolve a stable renderer source for an owned Session reference or explicit absence.
+     * @param reference - active reference supplied by the Provider owner, or absence.
+     * @returns the binding source, which falls back to the absent projection when its generation ends.
+     * @throws when the reference does not belong to the active Controller generation.
+     */
+    bindingSource(reference: SessionReference | undefined): HostObservable<StandardSourceBinding>;
+    /**
+     * Register one Session-scoped standard-source contribution.
+     * @param descriptor - static member roster and per-binding resolver.
+     * @returns disposer owned by the caller's Cordis fiber.
+     */
+    provide<const Hooks extends SessionSourceRoster = undefined, const KeyedHooks extends SessionSourceRoster = undefined, const Props extends SessionSourceRoster = undefined>(descriptor: SessionSourceDescriptor<Hooks, KeyedHooks, Props>): () => void;
+    /**
+     * Register one pending-interaction domain and return its publication function.
+     * Domain teardown first removes its visible values, then delegates and awaits
+     * every still-active owner request.
+     * @param precedence - deterministic cross-domain precedence; larger values win.
+     * @returns a function that publishes one interaction and its teardown delegation.
+     */
+    registerPendingInteraction<T extends SessionPendingInteractionBase>(precedence: (interaction: T) => number): PendingInteractionPublisher<T>;
+    private rebuildBindings;
+    private sourceFor;
+    private publishMain;
+    private watchMainRetention;
+    private publishPendingInteractions;
+    private observeRunning;
+    private reconcileStatus;
+    private isMain;
+    private publishStatus;
+    private createMaterializedBinding;
+    private materialize;
+    private materializeAbsent;
+}
+/** Required Controller and renderer services. */
+export declare const inject: string[];
+/**
+ * Install the Session root source and scoped adapter.
+ * @param ctx - Client Cordis context.
+ */
+export declare function apply(ctx: Context): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/session-provider.d.ts

@@ -0,0 +1,11 @@
+/** Session-owned rendering semantics for the standard SessionProvider seat. */
+import type { ReactNode } from 'react';
+import type { SessionAreaProps, StandardSourceBinding } from '@qilin-agent/client-ui-slots';
+/**
+ * Render the selected Session body or its empty branch.
+ * @param binding - current Session scope binding.
+ * @param props - standard Session area render props.
+ * @returns the selected Session subtree.
+ */
+export declare function renderSessionArea(binding: StandardSourceBinding, { empty, children }: SessionAreaProps): ReactNode;
+//# sourceMappingURL=session-provider.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Host loader entry for the browser-only Session UI adapter. */
+/** Provides no Host-side behavior. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@qilin-agent/client-ui-session",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Session Controller adapter for React and session-scoped slots",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-session"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "qilin": {
+    "client": {
+      "inject": [
+        "@qilin-agent/api-remotes",
+        "@qilin-agent/api-session-controller",
+        "@qilin-agent/client-ui-renderer"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/api-remotes": "3.1.3",
+    "@qilin-agent/api-session-controller": "3.1.3",
+    "@qilin-agent/client-store": "3.1.3",
+    "@qilin-agent/client-ui-renderer": "3.1.3",
+    "@qilin-agent/client-ui-slots": "3.1.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/util-values": "3.1.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }