@qilin-agent/client-ui-message-feedback 0.0.0-stage → 3.1.3

package/lib/index.js

@@ -0,0 +1,11 @@
+//#region lib/types/index.js
+/**
+* Message feedback surface plugin, node half. Pure UI plugin: the empty apply
+* exists so the plugin appears in the host cordis.yml / Loader; the browser
+* half ships via exports["./client"], discovered through the package.json
+* qilin.client declaration.
+*/
+/** Host plugin body — no host-side behavior for this surface plugin. */
+function apply() {}
+//#endregion
+export { apply };

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

@@ -0,0 +1,16 @@
+/**
+ * The feedback dialog and its acknowledgement and failure toasts, rendered as one entry
+ * of `conversation.input.overlay` so each Session owns exactly one of each.
+ * The Modal and the Toast both portal to `document.body`; the overlay slot
+ * only supplies the per-session controller and the composer card the toast
+ * centers over.
+ * @module @qilin-agent/client-ui-message-feedback/client/FeedbackDialog
+ */
+import type { FeedbackDialogProps } from './slots.ts';
+/**
+ * Render one Session's feedback dialog and toast.
+ * @param props - the dialog hook, the draft verbs, and the locale seat.
+ * @returns the modal while a target is open and either toast while it is showing.
+ */
+export declare function FeedbackDialog({ useDialog, edit, submit, dismiss, dismissFailure, dismissToast, t, }: FeedbackDialogProps): import("react").JSX.Element;
+//# sourceMappingURL=FeedbackDialog.d.ts.map

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

@@ -0,0 +1,17 @@
+/**
+ * Per-message feedback controls: the Like/Dislike pair inside the assistant
+ * message's IconActions row, between copy and branch. Either rating opens the
+ * Session's feedback dialog, whose submission records that judgment with its
+ * category and text. Clicking the recorded rating retracts it. A recorded rating
+ * shows the filled glyph so the signal survives a pointer leaving the row.
+ * @module @qilin-agent/client-ui-message-feedback/client/MessageFeedbackActions
+ */
+import type { MessageFeedbackActionProps } from './slots.ts';
+/**
+ * One message's feedback controls.
+ * @param props - the owner's message identity, the injected verbs, and the
+ * shared feedback hook.
+ * @returns the rating buttons with any failure notice beside them.
+ */
+export declare function MessageFeedbackActions({ messageId, ensure, current, retract, openDialog, useFeedback, t, }: MessageFeedbackActionProps): import("react").JSX.Element;
+//# sourceMappingURL=MessageFeedbackActions.d.ts.map

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

@@ -0,0 +1,127 @@
+/**
+ * Browser-local object layer over one Session's durable message-feedback
+ * sidecar. The Host owns per-item compare-and-set: every mutation carries the
+ * version this controller last observed, and a `version-conflict` reply carries
+ * the authoritative item, so a lost race reconciles from the reply itself
+ * instead of refetching the whole Session.
+ * @module @qilin-agent/client-ui-message-feedback/client/controller
+ */
+import type { HostObservable } from '@qilin-agent/client-ui-slots';
+import type { ClientRemote, MessageId } from '@qilin-agent/api-remotes/client';
+import type { SessionId } from '@qilin-agent/session/types';
+import type { FeedbackRecord } from '@qilin-agent/command-feedback/types';
+import type { MessageFeedbackItem, MessageFeedbackRating } from '@qilin-agent/message-feedback/types';
+/** Load state of the one list read that seeds every per-message control. */
+export type MessageFeedbackStatus = 'cold' | 'loading' | 'ready' | 'error';
+/** Immutable view published to every per-message control in one Session. */
+export interface MessageFeedbackView {
+    status: MessageFeedbackStatus;
+    /** Current item per message, keyed by the addressed message id. */
+    items: ReadonlyMap<MessageId, MessageFeedbackItem>;
+    /** Reason the last load failed, cleared by the next successful load. */
+    error: string | null;
+}
+/** Rejected branch shared by every settled action. */
+export interface MessageFeedbackActionFailure {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/** Settled action shape rendered by the message-level controls. */
+export type MessageFeedbackActionResult = {
+    ok: true;
+} | MessageFeedbackActionFailure;
+/**
+ * Human-readable text for one business failure code.
+ * @param code - the Host's business failure code.
+ * @returns the developer-facing description carried in the failure branch.
+ */
+export declare function describe(code: string): string;
+/**
+ * Per-session feedback object layer. One instance backs every per-message
+ * control in that Session, so a single list read seeds them all.
+ */
+export declare class MessageFeedbackController implements HostObservable<MessageFeedbackView> {
+    private readonly remote;
+    private readonly sessionId;
+    private view;
+    private readonly listeners;
+    private loadPromise;
+    private operationTail;
+    private disposed;
+    /**
+     * @param remote - the messageFeedback Remote namespace.
+     * @param sessionId - Session owning every addressed assistant message.
+     */
+    constructor(remote: ClientRemote['messageFeedback'], sessionId: SessionId);
+    /** Return the cached immutable view. */
+    getSnapshot: () => MessageFeedbackView;
+    /** Subscribe to view replacement. */
+    subscribe: (listener: () => void) => (() => void);
+    /**
+     * Load once; a failed load stays retryable.
+     * @returns the settled load result, shared by concurrent callers.
+     */
+    ensure(): Promise<MessageFeedbackActionResult>;
+    /**
+     * Re-read the authoritative list, collapsing concurrent callers onto one
+     * in-flight read.
+     *
+     * This is the unserialized read used to seed a cold controller, where no
+     * mutation can be in flight yet. A reconnect must use {@link resync} instead:
+     * an unserialized list response can otherwise arrive after a newer mutation's
+     * reply and overwrite the version that mutation just committed.
+     * @returns the settled reload result.
+     */
+    refresh(): Promise<MessageFeedbackActionResult>;
+    /**
+     * Re-read the list behind this Session's queued mutations, so a reconnect
+     * cannot resurrect a version an in-flight mutation already replaced.
+     * @returns the settled reload result.
+     */
+    resync(): Promise<MessageFeedbackActionResult>;
+    /**
+     * Create or replace feedback for one message, comparing against the version
+     * this controller last observed. The item stores exactly `entry`: an entry
+     * without a note or category replaces whatever the stored item carried.
+     * @param messageId - target assistant message.
+     * @param rating - desired judgment.
+     * @param entry - explanation and category to store with the judgment.
+     * @returns the settled mutation result.
+     */
+    rate(messageId: MessageId, rating: MessageFeedbackRating, entry?: FeedbackRecord): Promise<MessageFeedbackActionResult>;
+    /**
+     * Retract one message's matching committed rating. The serialized operation
+     * rechecks the current item and becomes a no-op if another operation already
+     * changed or removed it, so a stale retraction can never record a bare rating.
+     * @param messageId - target assistant message.
+     * @param rating - judgment the human asked to retract.
+     * @returns the settled mutation result.
+     */
+    retract(messageId: MessageId, rating: MessageFeedbackRating): Promise<MessageFeedbackActionResult>;
+    /** Commit one put against the observed version and reconcile a conflict. */
+    private putCommitted;
+    /** Commit one delete against the observed version and reconcile a conflict. */
+    private deleteCommitted;
+    /** Drop subscribers and refuse further work when the owning fiber unloads. */
+    dispose(): void;
+    /** Fetch the whole sidecar and publish it as the seeded view. */
+    private load;
+    /**
+     * Serialize one mutation behind this Session's prior mutation so queued
+     * operations always compare against the committed version.
+     */
+    private mutate;
+    /**
+     * Replace one message's entry, keeping every other entry's identity. Only a
+     * `mutate` operation reaches this, and `mutate` refuses admission once the
+     * controller is disposed, so no disposal guard belongs here; `publish` is
+     * the single place that stops notifying after listeners are dropped.
+     */
+    private commit;
+    /** Replace the view and contain subscriber failures at the observable boundary. */
+    private publish;
+}
+//# sourceMappingURL=controller.d.ts.map

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

@@ -0,0 +1,83 @@
+/**
+ * Headless state of one Session's feedback dialog and its acknowledgement and
+ * failure toasts. One form serves two targets: the Session itself (a bare `/feedback`)
+ * and one assistant message (Like or Dislike). The overlay view renders from
+ * the store and raises the acknowledgement after a successful submission.
+ * @module @qilin-agent/client-ui-message-feedback/client/dialog
+ */
+import { type SnapshotStore } from '@qilin-agent/client-store';
+import type { MessageId } from '@qilin-agent/api-remotes/client';
+import type { FeedbackCategory, FeedbackRecord } from '@qilin-agent/command-feedback/types';
+import type { MessageFeedbackRating } from '@qilin-agent/message-feedback/types';
+import type { MessageFeedbackActionResult } from './controller.ts';
+/** What one open dialog submits to. */
+export type FeedbackDialogTarget = {
+    readonly kind: 'session';
+} | {
+    readonly kind: 'message';
+    readonly messageId: MessageId;
+    readonly rating: MessageFeedbackRating;
+};
+/** Dialog and toast state the overlay view renders from. */
+export interface FeedbackDialogState {
+    /** Target the dialog is open for; null while closed. */
+    readonly target: FeedbackDialogTarget | null;
+    readonly category: FeedbackCategory | null;
+    readonly text: string;
+    /** A submission is in flight; the form ignores edits and submits until it settles. */
+    readonly submitting: boolean;
+    /** Failure code of the last submission from this open; null when none. */
+    readonly failure: string | null;
+    /** Sequence of the acknowledgement toast on screen; 0 while none. */
+    readonly toast: number;
+}
+/**
+ * Record one submission against its target.
+ * @param target - the open target.
+ * @param entry - the trimmed text and the category, each present only when given.
+ */
+export type FeedbackSubmit = (target: FeedbackDialogTarget, entry: FeedbackRecord) => Promise<MessageFeedbackActionResult>;
+/** Per-session dialog controller; one instance backs the overlay entry and every message control. */
+export declare class FeedbackDialogController {
+    private readonly submit;
+    /** Dialog state store (the overlay entry subscribes here). */
+    readonly state: SnapshotStore<FeedbackDialogState>;
+    /** Bumped by every open, dismiss, and dispose so a late settlement can tell its draft is gone. */
+    private generation;
+    private toastSeq;
+    /**
+     * @param submit - records one submission; the owner routes it by target.
+     */
+    constructor(submit: FeedbackSubmit);
+    /**
+     * Open the dialog with an empty draft, replacing any open draft.
+     * @param target - what the submission records against.
+     */
+    open(target: FeedbackDialogTarget): void;
+    /** Close the dialog and discard the draft; a toast on screen stays. */
+    dismiss(): void;
+    /**
+     * Replace part of the draft while it is editable.
+     * @param draft - the category (null clears it) or the text as typed.
+     */
+    edit(draft: Partial<Pick<FeedbackDialogState, 'category' | 'text'>>): void;
+    /**
+     * Submit the draft; an empty draft is a valid submission. Success closes the
+     * dialog and raises the acknowledgement toast; a failure keeps the dialog
+     * open and publishes its code for the failure toast.
+     * @returns after the submission settles.
+     */
+    submitDraft(): Promise<void>;
+    /** Clear the current failure toast without closing its draft. */
+    dismissFailure(): void;
+    /** Show the acknowledgement toast; a toast already on screen restarts. */
+    private acknowledge;
+    /**
+     * Retire one toast after its fade; a newer toast is left alone.
+     * @param seq - the toast sequence the view finished showing.
+     */
+    dismissToast(seq: number): void;
+    /** Scope-teardown disposer: drop the draft and the toast, orphan in-flight work. */
+    dispose(): void;
+}
+//# sourceMappingURL=dialog.d.ts.map

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

@@ -0,0 +1,22 @@
+/**
+ * Feedback surface plugin, browser half: the Like/Dislike entry in the
+ * conversation.chat.assistant-actions strip, the feedback dialog and its
+ * acknowledgement and failure toasts in conversation.input.overlay, and the `/feedback`
+ * decoration that opens the dialog from the composer menu or a bare typed
+ * command. One FeedbackSurface per Session backs every entry in that Session.
+ * @module @qilin-agent/client-ui-message-feedback/client
+ */
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+export type { MessageFeedbackActionFailure, MessageFeedbackActionResult, MessageFeedbackStatus, MessageFeedbackView, } from './controller.ts';
+export type { FeedbackDialogState, FeedbackDialogTarget, FeedbackSubmit } from './dialog.ts';
+export type { FeedbackDialogInjected, FeedbackDialogProps, MessageFeedbackActionProps, MessageFeedbackInjected, } from './slots.ts';
+export type { MessageFeedbackKey } from './locales.ts';
+/** Required services: the slot registry, the two Remote namespaces, and the copy. */
+export declare const inject: string[];
+/**
+ * Client plugin body: the per-message feedback entry, the Session's dialog
+ * entry, the `/feedback` decoration, and their per-session surfaces.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,56 @@
+/** `feedback` namespace dictionaries. */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'action.like': string;
+    'action.likeActive': string;
+    'action.dislike': string;
+    'action.dislikeActive': string;
+    'dialog.title': string;
+    'dialog.categories': string;
+    'dialog.detail': string;
+    'dialog.hint': string;
+    'category.task-result': string;
+    'category.instruction-following': string;
+    'category.product-interaction': string;
+    'category.service-stability': string;
+    'category.resource-cost': string;
+    'category.security-privacy-permission': string;
+    'category.other': string;
+    'toast.recorded': string;
+    'error.conflict': string;
+    'error.load': string;
+    'error.generic': string;
+    'error.noteTooLarge': string;
+};
+/** The feedback namespace key union. */
+export type MessageFeedbackKey = keyof typeof zh;
+declare module '@qilin-agent/client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The feedback surface's copy: the message controls, the dialog, and the acknowledgement. */
+        feedback: MessageFeedbackKey;
+    }
+}
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'action.like': string;
+    'action.likeActive': string;
+    'action.dislike': string;
+    'action.dislikeActive': string;
+    'dialog.title': string;
+    'dialog.categories': string;
+    'dialog.detail': string;
+    'dialog.hint': string;
+    'category.task-result': string;
+    'category.instruction-following': string;
+    'category.product-interaction': string;
+    'category.service-stability': string;
+    'category.resource-cost': string;
+    'category.security-privacy-permission': string;
+    'category.other': string;
+    'toast.recorded': string;
+    'error.conflict': string;
+    'error.load': string;
+    'error.generic': string;
+    'error.noteTooLarge': string;
+};
+//# sourceMappingURL=locales.d.ts.map

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

@@ -0,0 +1,70 @@
+/**
+ * The injected faces of this package's two entries. The
+ * 'conversation.chat.assistant-actions' and 'conversation.input.overlay'
+ * slots are declared and typed by ui-chat and ui-conversation; this package
+ * only contributes entries, so no SlotMap merge lives here. Live state
+ * arrives through the `hooks` compartment (the framework standard kit binds
+ * `feedback` into `useFeedback` and `dialog` into `useDialog`).
+ * @module @qilin-agent/client-ui-message-feedback/client/slots
+ */
+import type { HostObservable, InjectFace, PropsLocale, PropsRuntime } from '@qilin-agent/client-ui-slots';
+import type { MessageId } from '@qilin-agent/api-remotes/client';
+import type { MessageFeedbackItem, MessageFeedbackRating } from '@qilin-agent/message-feedback/types';
+import type { MessageFeedbackActionResult, MessageFeedbackView } from './controller.ts';
+import type { FeedbackDialogState } from './dialog.ts';
+/** Injected business face of one assistant-message feedback entry. */
+export interface MessageFeedbackInjected {
+    hooks: {
+        /** The owning Session's feedback view, shared by every message control. */
+        feedback: HostObservable<MessageFeedbackView>;
+    };
+    /** Load the Session's feedback once, on first interaction. */
+    ensure: () => Promise<MessageFeedbackActionResult>;
+    /**
+     * The committed item as this Session's controller last observed it.
+     * @param messageId - target assistant message.
+     */
+    current: (messageId: MessageId) => MessageFeedbackItem | undefined;
+    /**
+     * Retract the requested judgment only while the committed rating still
+     * matches; a concurrent change makes the serialized operation a no-op.
+     * @param messageId - target assistant message.
+     * @param rating - judgment the human asked to retract.
+     */
+    retract: (messageId: MessageId, rating: MessageFeedbackRating) => Promise<MessageFeedbackActionResult>;
+    /**
+     * Open the Session's feedback dialog for one message and judgment; its
+     * submission records that rating with the dialog's category and text.
+     * @param messageId - target assistant message.
+     * @param rating - judgment to record on submission.
+     */
+    openDialog: (messageId: MessageId, rating: MessageFeedbackRating) => void;
+}
+/** Full props of one assistant-message feedback entry. */
+export type MessageFeedbackActionProps = PropsRuntime<'conversation.chat.assistant-actions'> & InjectFace<MessageFeedbackInjected> & PropsLocale<'feedback'>;
+/** Injected business face of the Session's feedback dialog entry. */
+export interface FeedbackDialogInjected {
+    hooks: {
+        /** The Session's dialog and toast state. */
+        dialog: HostObservable<FeedbackDialogState>;
+    };
+    /**
+     * Replace part of the draft: the category (null clears it) or the text.
+     * @param draft - the members to replace.
+     */
+    edit: (draft: Partial<Pick<FeedbackDialogState, 'category' | 'text'>>) => void;
+    /** Submit the draft to the open target. */
+    submit: () => Promise<void>;
+    /** Close the dialog and discard the draft. */
+    dismiss: () => void;
+    /** Retire the current submission-failure toast without closing its draft. */
+    dismissFailure: () => void;
+    /**
+     * Retire the toast the view finished showing.
+     * @param seq - the toast sequence.
+     */
+    dismissToast: (seq: number) => void;
+}
+/** Full props of the feedback dialog overlay entry. */
+export type FeedbackDialogProps = InjectFace<FeedbackDialogInjected> & PropsLocale<'feedback'>;
+//# sourceMappingURL=slots.d.ts.map

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

@@ -0,0 +1,30 @@
+/**
+ * One Session's feedback surface: the message-feedback object layer and the
+ * dialog controller, plus the routing between them. A message target puts a
+ * selected judgment through the message controller; the Session target records
+ * through the `sessionFeedback` Remote.
+ * @module @qilin-agent/client-ui-message-feedback/client/surface
+ */
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+import type { SessionId } from '@qilin-agent/session/types';
+import { MessageFeedbackController } from './controller.ts';
+import { FeedbackDialogController } from './dialog.ts';
+/** The per-session pair behind every entry of one Session. */
+export declare class FeedbackSurface {
+    private readonly ctx;
+    private readonly sessionId;
+    /** The Session's message-feedback object layer, shared by every message control. */
+    readonly feedback: MessageFeedbackController;
+    /** The Session's dialog and toast state, shared by the overlay entry and the message controls. */
+    readonly dialog: FeedbackDialogController;
+    /**
+     * @param ctx - the browser plugin context carrying both feedback Remotes.
+     * @param sessionId - Session owning the transcript and the remark.
+     */
+    constructor(ctx: ClientContext, sessionId: SessionId);
+    /** Record one Session-level remark through the sessionFeedback Remote. */
+    private recordSession;
+    /** Drop both controllers when the owning fiber unloads. */
+    dispose(): void;
+}
+//# sourceMappingURL=surface.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Message feedback surface plugin, node half. Pure UI plugin: the empty apply
+ * exists so the plugin appears in the host cordis.yml / Loader; the browser
+ * half ships via exports["./client"], discovered through the package.json
+ * qilin.client declaration.
+ */
+/** Host plugin body — no host-side behavior for this surface plugin. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@qilin-agent/client-ui-message-feedback",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "The Web feedback surface: per-message Like/Dislike in the assistant-message action strip and the feedback dialog behind both ratings and /feedback, backed by the messageFeedback and sessionFeedback Host Remotes",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-message-feedback"
+  },
+  "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/client-locale",
+        "@qilin-agent/client-ui-conversation",
+        "@qilin-agent/client-ui-renderer",
+        "@qilin-agent/client-ui-commands"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@qilin-agent/client-locale": "3.1.3",
+    "@qilin-agent/client-test-runtime": "3.1.3",
+    "@qilin-agent/client-ui-primitives": "3.1.3",
+    "@qilin-agent/api-remotes": "3.1.3",
+    "@qilin-agent/client-ui-conversation": "3.1.3",
+    "@qilin-agent/client-connection": "3.1.3",
+    "@qilin-agent/client-ui-slots": "3.1.3",
+    "@qilin-agent/message-feedback": "3.1.3",
+    "@qilin-agent/remote-mock": "3.1.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/client-ui-renderer": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/typert-protocol": "3.1.3",
+    "@qilin-agent/client-ui-chat": "3.1.3",
+    "@qilin-agent/client-ui-session": "3.1.3",
+    "@qilin-agent/client-ui-commands": "3.1.3",
+    "@qilin-agent/command-feedback": "3.1.3",
+    "@qilin-agent/client-store": "3.1.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }