@qilin-agent/client-ui-primitives 0.0.0-stage → 3.1.4

package/lib/types/seal-glyphs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Glyph outlines for the QiLin seal, extracted once from a system CJK face
+ * and normalized to a unit box so the mark carries no runtime font dependency.
+ */
+/** 麒 (U+9E92), normalized to a unit box. */
+export declare const SEAL_GLYPH_QI = "M0.42 0.84Q0.42 0.86 0.45 0.86Q0.47 0.86 0.48 0.86Q0.49 0.86 0.5 0.85Q0.5 0.84 0.51 0.83Q0.51 0.81 0.51 0.79Q0.53 0.81 0.55 0.81Q0.56 0.82 0.59 0.82Q0.57 0.85 0.56 0.88Q0.55 0.9 0.53 0.91Q0.52 0.93 0.49 0.93Q0.47 0.94 0.44 0.94Q0.41 0.94 0.39 0.93Q0.38 0.93 0.37 0.92Q0.36 0.92 0.35 0.91Q0.35 0.9 0.35 0.89V0.63Q0.35 0.61 0.35 0.59Q0.35 0.58 0.35 0.57Q0.35 0.56 0.35 0.55Q0.35 0.54 0.34 0.54Q0.37 0.54 0.39 0.54Q0.4 0.54 0.42 0.54Q0.44 0.54 0.44 0.55Q0.44 0.55 0.43 0.56Q0.42 0.57 0.42 0.61V0.68Q0.44 0.65 0.46 0.63Q0.47 0.61 0.48 0.59Q0.49 0.61 0.51 0.62Q0.52 0.63 0.54 0.64Q0.55 0.64 0.55 0.65Q0.54 0.65 0.54 0.65Q0.53 0.65 0.53 0.66Q0.52 0.66 0.51 0.67Q0.5 0.68 0.48 0.7Q0.45 0.73 0.42 0.76ZM0.92 0.99Q0.9 0.95 0.87 0.9Q0.84 0.85 0.79 0.8L0.86 0.76Q0.9 0.81 0.94 0.86Q0.97 0.9 1 0.94ZM0.74 0.81Q0.74 0.81 0.73 0.82Q0.72 0.83 0.7 0.85Q0.68 0.87 0.66 0.91Q0.63 0.94 0.59 1Q0.57 0.98 0.55 0.97Q0.54 0.96 0.51 0.95Q0.54 0.93 0.56 0.91Q0.58 0.89 0.6 0.86Q0.62 0.84 0.63 0.82Q0.65 0.79 0.66 0.76Q0.68 0.77 0.7 0.78Q0.72 0.79 0.74 0.79Q0.75 0.8 0.75 0.8Q0.75 0.81 0.74 0.81ZM0.25 0.84Q0.26 0.83 0.28 0.82Q0.29 0.81 0.3 0.8Q0.3 0.81 0.31 0.83Q0.32 0.84 0.33 0.86L0.25 0.92Q0.23 0.93 0.21 0.95Q0.19 0.97 0.18 0.97Q0.17 0.96 0.16 0.94Q0.15 0.92 0.14 0.91Q0.15 0.9 0.16 0.9Q0.17 0.89 0.18 0.89V0.65Q0.18 0.58 0.18 0.55Q0.2 0.55 0.22 0.55Q0.24 0.55 0.26 0.55Q0.27 0.55 0.27 0.55Q0.27 0.56 0.27 0.56Q0.26 0.57 0.25 0.58Q0.25 0.58 0.25 0.59V0.64Q0.29 0.64 0.31 0.64Q0.32 0.64 0.33 0.64V0.71Q0.32 0.71 0.3 0.71Q0.28 0.71 0.25 0.71ZM0.61 0.15Q0.61 0.11 0.61 0.07Q0.61 0.03 0.6 0.01Q0.63 0.01 0.65 0.01Q0.67 0.01 0.69 0.01Q0.7 0.01 0.7 0.01Q0.71 0.02 0.7 0.03Q0.69 0.03 0.69 0.04Q0.68 0.05 0.68 0.06V0.15H0.84Q0.84 0.09 0.84 0.05Q0.83 0.02 0.83 0Q0.86 0.01 0.88 0.01Q0.9 0.01 0.93 0.01Q0.94 0.01 0.94 0.01Q0.95 0.02 0.94 0.02Q0.93 0.03 0.92 0.04Q0.92 0.05 0.92 0.06V0.15Q0.93 0.15 0.95 0.14Q0.97 0.14 0.99 0.14V0.21Q0.97 0.21 0.95 0.21Q0.93 0.21 0.92 0.21V0.67Q0.93 0.67 0.96 0.67Q0.98 0.67 1 0.67V0.75Q0.98 0.74 0.97 0.74Q0.95 0.74 0.92 0.74Q0.9 0.74 0.86 0.74Q0.82 0.74 0.76 0.74Q0.7 0.74 0.67 0.74Q0.63 0.74 0.6 0.74Q0.58 0.74 0.56 0.74Q0.55 0.74 0.53 0.75V0.67Q0.55 0.67 0.57 0.67Q0.6 0.67 0.61 0.67V0.21Q0.6 0.21 0.58 0.21Q0.56 0.21 0.54 0.21V0.14Q0.56 0.14 0.58 0.14Q0.6 0.15 0.61 0.15ZM0.68 0.67H0.84V0.55H0.68ZM0.84 0.31V0.21H0.68V0.31ZM0.68 0.38V0.49H0.84V0.38ZM0.49 0.47V0.35H0.42V0.47ZM0.35 0.47V0.35H0.28V0.47ZM0.13 0.35Q0.13 0.38 0.13 0.41Q0.13 0.44 0.13 0.47H0.22V0.35ZM0.13 0.17V0.3H0.22V0.17ZM0.42 0.3Q0.44 0.3 0.46 0.3Q0.48 0.29 0.49 0.29Q0.51 0.29 0.53 0.29Q0.54 0.29 0.55 0.29Q0.55 0.3 0.55 0.34Q0.55 0.37 0.55 0.41Q0.55 0.45 0.55 0.48Q0.55 0.52 0.55 0.53Q0.53 0.53 0.48 0.53Q0.43 0.52 0.38 0.52H0.13Q0.13 0.61 0.12 0.68Q0.12 0.74 0.11 0.79Q0.1 0.84 0.09 0.88Q0.08 0.92 0.06 0.96Q0.04 0.94 0.03 0.92Q0.01 0.91 0 0.89Q0.02 0.86 0.03 0.83Q0.04 0.8 0.05 0.76Q0.06 0.72 0.06 0.67Q0.06 0.62 0.07 0.54Q0.07 0.46 0.07 0.36Q0.07 0.25 0.06 0.11Q0.08 0.11 0.14 0.11Q0.19 0.11 0.27 0.11Q0.26 0.09 0.25 0.06Q0.24 0.04 0.22 0.02L0.32 0Q0.32 0.02 0.33 0.05Q0.34 0.08 0.35 0.11Q0.39 0.11 0.42 0.11Q0.45 0.11 0.47 0.11Q0.49 0.11 0.5 0.11Q0.51 0.1 0.52 0.1V0.18Q0.51 0.18 0.48 0.18Q0.45 0.18 0.42 0.18ZM0.28 0.17V0.3H0.35V0.17Z";
+/** 麟 (U+9E9F), normalized to a unit box. */
+export declare const SEAL_GLYPH_LIN = "M0.53 0.66Q0.55 0.68 0.57 0.71Q0.59 0.73 0.6 0.74Q0.61 0.71 0.61 0.68Q0.61 0.65 0.61 0.62H0.55Q0.54 0.63 0.54 0.64Q0.53 0.65 0.53 0.66ZM0.25 0.18V0.28H0.31V0.18ZM0.13 0.18V0.28H0.19V0.18ZM0.13 0.44H0.19V0.34H0.13ZM0.31 0.44V0.34H0.25V0.44ZM0.42 0.44V0.34H0.37V0.44ZM0.83 0.76V0.62Q0.79 0.62 0.76 0.62Q0.74 0.63 0.72 0.63V0.55Q0.76 0.56 0.83 0.56Q0.83 0.52 0.83 0.5Q0.83 0.48 0.82 0.47Q0.87 0.48 0.9 0.47Q0.92 0.47 0.92 0.48Q0.92 0.48 0.91 0.49Q0.9 0.5 0.9 0.5Q0.9 0.51 0.9 0.52V0.56Q0.92 0.56 0.94 0.56Q0.97 0.56 0.99 0.55V0.63Q0.97 0.63 0.95 0.63Q0.93 0.62 0.9 0.62V0.76Q0.92 0.76 0.95 0.75Q0.98 0.75 1 0.75V0.83Q0.99 0.83 0.96 0.82Q0.93 0.82 0.9 0.82Q0.9 0.85 0.9 0.88Q0.9 0.9 0.9 0.92Q0.9 0.93 0.9 0.95Q0.9 0.96 0.91 0.98H0.82Q0.83 0.96 0.83 0.95Q0.83 0.94 0.83 0.92Q0.83 0.9 0.83 0.88Q0.83 0.86 0.83 0.82H0.77Q0.77 0.83 0.77 0.83Q0.77 0.83 0.77 0.84L0.7 0.84Q0.71 0.78 0.71 0.74Q0.71 0.7 0.71 0.66Q0.74 0.67 0.78 0.67Q0.79 0.66 0.79 0.67Q0.79 0.67 0.78 0.68Q0.78 0.69 0.78 0.7Q0.78 0.72 0.77 0.76ZM0.37 0.62Q0.39 0.6 0.41 0.59Q0.43 0.58 0.44 0.56Q0.46 0.59 0.48 0.61Q0.5 0.58 0.51 0.55Q0.52 0.52 0.53 0.48Q0.57 0.49 0.6 0.5Q0.62 0.5 0.6 0.52Q0.59 0.52 0.59 0.53Q0.58 0.54 0.58 0.56Q0.63 0.56 0.65 0.56Q0.67 0.55 0.68 0.55Q0.68 0.64 0.67 0.7Q0.66 0.77 0.64 0.82Q0.62 0.87 0.58 0.91Q0.54 0.96 0.47 0.99Q0.46 0.97 0.44 0.96Q0.43 0.94 0.41 0.93Q0.47 0.91 0.51 0.88Q0.55 0.85 0.57 0.81Q0.56 0.79 0.54 0.77Q0.52 0.74 0.49 0.72Q0.49 0.72 0.49 0.73Q0.49 0.73 0.48 0.73Q0.47 0.72 0.46 0.71Q0.45 0.7 0.43 0.7Q0.46 0.66 0.47 0.63Q0.46 0.64 0.43 0.65Q0.41 0.66 0.37 0.68V0.81Q0.37 0.83 0.38 0.83Q0.39 0.84 0.41 0.84Q0.42 0.84 0.43 0.83Q0.44 0.81 0.45 0.78Q0.46 0.79 0.47 0.8Q0.49 0.8 0.51 0.81Q0.5 0.84 0.49 0.85Q0.48 0.87 0.46 0.88Q0.45 0.89 0.44 0.9Q0.43 0.9 0.41 0.9Q0.38 0.9 0.36 0.9Q0.34 0.89 0.33 0.89Q0.32 0.88 0.31 0.86Q0.31 0.85 0.31 0.82V0.51H0.12Q0.12 0.61 0.12 0.68Q0.12 0.75 0.11 0.79Q0.1 0.84 0.09 0.87Q0.08 0.91 0.07 0.95Q0.05 0.91 0.03 0.9Q0.02 0.88 0 0.88Q0.05 0.79 0.06 0.59Q0.07 0.4 0.05 0.11Q0.06 0.11 0.11 0.12Q0.16 0.12 0.25 0.12Q0.24 0.1 0.23 0.08Q0.22 0.06 0.2 0.04L0.3 0.01Q0.31 0.04 0.32 0.06Q0.33 0.09 0.34 0.12Q0.39 0.12 0.44 0.12Q0.48 0.11 0.5 0.11V0.19Q0.49 0.19 0.47 0.19Q0.46 0.18 0.44 0.18Q0.42 0.18 0.4 0.18Q0.38 0.18 0.37 0.18V0.28Q0.4 0.28 0.43 0.27Q0.47 0.27 0.48 0.27Q0.48 0.28 0.48 0.29Q0.48 0.3 0.48 0.31Q0.48 0.32 0.48 0.34Q0.48 0.36 0.48 0.39Q0.48 0.42 0.48 0.44Q0.48 0.46 0.48 0.48Q0.48 0.49 0.48 0.5Q0.48 0.51 0.48 0.52Q0.45 0.51 0.37 0.51ZM0.22 0.62Q0.25 0.62 0.27 0.62Q0.28 0.62 0.3 0.62Q0.3 0.63 0.3 0.65Q0.3 0.66 0.3 0.68Q0.28 0.68 0.27 0.68Q0.25 0.68 0.22 0.68V0.82Q0.24 0.81 0.26 0.8Q0.28 0.79 0.3 0.78Q0.3 0.8 0.3 0.81Q0.3 0.82 0.31 0.84L0.21 0.89Q0.19 0.9 0.18 0.91Q0.16 0.92 0.15 0.93Q0.15 0.91 0.14 0.9Q0.13 0.88 0.12 0.85Q0.14 0.85 0.16 0.84V0.65Q0.16 0.54 0.15 0.51Q0.19 0.52 0.22 0.52Q0.23 0.52 0.23 0.52Q0.23 0.53 0.23 0.53Q0.22 0.54 0.22 0.55Q0.22 0.55 0.22 0.56ZM0.57 0.04Q0.59 0.07 0.61 0.1Q0.63 0.14 0.64 0.17L0.57 0.2Q0.56 0.14 0.51 0.08ZM0.93 0.06Q0.94 0.06 0.94 0.07Q0.94 0.08 0.93 0.08Q0.92 0.08 0.92 0.08Q0.91 0.09 0.9 0.1Q0.89 0.11 0.88 0.14Q0.87 0.16 0.85 0.19Q0.83 0.18 0.82 0.17Q0.8 0.17 0.78 0.16Q0.8 0.13 0.82 0.1Q0.83 0.07 0.84 0.03Q0.85 0.03 0.86 0.04Q0.87 0.04 0.89 0.05Q0.9 0.05 0.91 0.05Q0.92 0.06 0.93 0.06ZM0.68 0.27Q0.66 0.31 0.65 0.33Q0.64 0.36 0.63 0.38Q0.61 0.4 0.59 0.42Q0.57 0.44 0.53 0.47Q0.52 0.45 0.52 0.44Q0.51 0.43 0.49 0.42Q0.51 0.4 0.53 0.39Q0.55 0.37 0.57 0.35Q0.58 0.33 0.6 0.31Q0.61 0.29 0.63 0.27Q0.61 0.27 0.59 0.27Q0.57 0.27 0.56 0.27Q0.54 0.27 0.52 0.27Q0.51 0.28 0.5 0.28V0.2Q0.51 0.2 0.52 0.21Q0.53 0.21 0.55 0.21Q0.57 0.21 0.6 0.21Q0.63 0.21 0.68 0.21V0.15Q0.68 0.09 0.68 0.07Q0.67 0.04 0.67 0.02Q0.69 0.02 0.71 0.02Q0.74 0.02 0.75 0.02Q0.76 0.02 0.77 0.03Q0.77 0.03 0.76 0.04Q0.75 0.05 0.75 0.06Q0.75 0.07 0.75 0.09V0.21Q0.81 0.21 0.85 0.21Q0.9 0.21 0.92 0.21Q0.94 0.21 0.95 0.21Q0.97 0.2 0.97 0.2V0.28Q0.97 0.27 0.95 0.27Q0.94 0.27 0.92 0.27Q0.9 0.27 0.87 0.27Q0.85 0.27 0.81 0.27Q0.83 0.29 0.84 0.31Q0.86 0.32 0.88 0.34Q0.9 0.35 0.93 0.36Q0.95 0.37 0.99 0.37Q0.97 0.39 0.96 0.41Q0.95 0.43 0.94 0.46Q0.87 0.43 0.83 0.38Q0.78 0.34 0.75 0.27H0.75V0.35Q0.75 0.4 0.75 0.44Q0.75 0.47 0.75 0.5H0.67Q0.67 0.47 0.68 0.43Q0.68 0.4 0.68 0.35Z";
+//# sourceMappingURL=seal-glyphs.d.ts.map

package/lib/types/settings-form/SettingsForm.d.ts

@@ -0,0 +1,46 @@
+/**
+ * One plugin's settings form as its page on the Plugins page shows it: the
+ * read-only notice when the deployment stores settings read-only, the
+ * plugin's controls, and the save that writes every staged edit. The page
+ * draws the plugin's title and one-liner itself.
+ *
+ * Only a save writes. Leaving the page drops every staged edit, so the form
+ * discards on unmount and offers no discard control. A form whose namespace
+ * the Host stopped serving says so in place of its controls rather than
+ * showing fields nothing would accept.
+ */
+import { type ReactNode } from 'react';
+import type { SettingsFormShell } from './form-model.ts';
+/** The copy the form frame renders, from the owning plugin's dictionary. */
+export interface SettingsFormLabels {
+    /** Shown in place of the controls while the namespace is not served. */
+    unavailable: string;
+    /** Shown over the controls while the document is read-only. */
+    readOnly: string;
+    /** Shown beside the save after a save the Host did not accept. */
+    saveFailed: string;
+    /** The save control. */
+    save: string;
+    /** The save control while a save is crossing the wire. */
+    saving: string;
+}
+/** Form chrome shared by every settings page. */
+export interface SettingsFormProps {
+    /** The frame's copy. */
+    labels: SettingsFormLabels;
+    /** The form state: availability, writability, and what a save would do. */
+    state: SettingsFormShell;
+    /** Write every staged edit. */
+    onSave: () => void;
+    /** Drop every staged edit; the form calls it when it leaves the page. */
+    onDiscard: () => void;
+    /** The plugin's controls. */
+    children: ReactNode;
+}
+/**
+ * Render one plugin's settings form.
+ * @param props - the form's copy and state, its controls, and the save and discard actions.
+ * @returns the form, or the unavailable line while the namespace is not served.
+ */
+export declare function SettingsForm(props: SettingsFormProps): import("react").JSX.Element;
+//# sourceMappingURL=SettingsForm.d.ts.map

package/lib/types/settings-form/fields.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The controls of a settings form. Each renders one field's label, its staged
+ * text, whether saving would leave an override, and — when one stands — the
+ * reset that stages a clear back to the composition layer. Nothing here
+ * writes: a control reports what the user typed, and the form's save is the
+ * single point where a draft becomes a document mutation.
+ */
+import { type ReactNode } from 'react';
+/** What every settings field control needs regardless of its value type. */
+export interface SettingsFieldProps {
+    /** Stable id associating the label with its control. */
+    id: string;
+    /** Visible label. */
+    label: string;
+    /** One-line explanation rendered under the control. */
+    hint: string;
+    /** Draft text this control renders. */
+    text: string;
+    /** True when saving would leave a user-layer entry for this field. */
+    overridden: boolean;
+    /** True when the draft is not a value this field accepts. */
+    invalid: boolean;
+    /** Copy for the overridden badge. */
+    overriddenLabel: string;
+    /** Copy for the reset control. */
+    resetLabel: string;
+    /** Copy shown in place of the hint while the draft is invalid. */
+    invalidLabel: string;
+    /** Disables every control (read-only document, or an unavailable namespace). */
+    disabled: boolean;
+    /** Stage draft text. */
+    onEdit: (text: string) => void;
+    /** Stage a clear so the field re-inherits the composition layer. */
+    onReset: () => void;
+}
+/**
+ * A staged value field. `numeric` only hints the keypad: which drafts a field
+ * accepts is decided by its spec, so the control never silently rewrites what
+ * the user typed.
+ * @param props - the field's copy, its staged text, and the edit actions.
+ * @returns the labelled control.
+ */
+export declare function SettingsValueField(props: Omit<SettingsFieldProps, 'hint'> & {
+    /** Optional explanation shown below the input. */
+    hint?: string;
+    /** Rules disclosed by the information button beside the label. */
+    help?: {
+        label: string;
+        content: ReactNode;
+    };
+    /** Hints a numeric keypad without narrowing what the control accepts. */
+    numeric?: boolean;
+    /** Placeholder shown while the draft is empty. */
+    placeholder?: string;
+}): import("react").JSX.Element;
+/**
+ * A write-only credential control. The value never rides a response, so the
+ * control reports only whether one is configured and starts blank; a blank
+ * draft writes nothing, which keeps the stored key rather than clearing it.
+ * The control asks browsers not to autofill saved login passwords.
+ * @param props - the field's copy, its staged text, and the configured state.
+ * @returns the labelled control.
+ */
+export declare function SettingsSecretField(props: Pick<SettingsFieldProps, 'id' | 'label' | 'hint' | 'text' | 'disabled' | 'onEdit'> & {
+    /** Whether the Host reports a configured credential for this reference. */
+    configured: boolean;
+    /** Copy describing the configured state. */
+    stateLabel: string;
+}): import("react").JSX.Element;
+//# sourceMappingURL=fields.d.ts.map

package/lib/types/settings-form/form-model.d.ts

@@ -0,0 +1,214 @@
+/**
+ * The staged form model behind a plugin's settings page.
+ *
+ * A card stages what the user types and writes it only when they save. Each
+ * settings write is a durable, revision-fenced document mutation, so a control
+ * that committed as it settled turned one edit into a write the user never
+ * asked for and could not preview; staged text makes what is on screen exactly
+ * what a save would store.
+ *
+ * A field shows its effective value — the user layer over the composition
+ * layer over the schema default — and whether the user layer carries it. That
+ * presence, not a value comparison, is what marks a field overridden: an
+ * override equal to the composition default is still an override.
+ */
+import { type SnapshotStore } from '@qilin-agent/client-store';
+/** What the model reads of one Host entry's form. */
+export interface SettingsFormScopeSnapshot<T> {
+    /** `ready` while the Host serves the entry to this client; the form renders nothing otherwise. */
+    status: 'loading' | 'ready' | 'unavailable';
+    /** Last accepted schema-resolved section; undefined before the first acceptance. */
+    value: T | undefined;
+    /** Composition layer the value resolves over: what a field reverts to once cleared. */
+    base: unknown;
+    /** Raw user layer as stored; a field's PRESENCE here is what marks it overridden. */
+    user: unknown;
+    /** Whether the Host document accepts writes. */
+    writable: boolean;
+    /** Revision the snapshot was read at; a save fences its mutation with the revision its drafts started from. */
+    revision: number | undefined;
+}
+/** One path edit a save sends, as the shared configuration form's `mutate` accepts it. */
+export type SettingsFormPathOp = {
+    op: 'set';
+    path: readonly string[];
+    value: unknown;
+} | {
+    op: 'unset';
+    path: readonly string[];
+};
+/** The entry form the model stages over: the reads and the atomic write of the form `ui-settings` shares per Host entry. */
+export interface SettingsFormScope<T> {
+    /** @returns the current sync snapshot. */
+    getSnapshot(): SettingsFormScopeSnapshot<T>;
+    /**
+     * Observe snapshot replacements.
+     * @param listener - invoked after each snapshot change.
+     * @returns the disposer removing this listener.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Apply ordered field edits in one revision-fenced write.
+     * @param ops - the edits, in staging order.
+     * @param expectedRevision - the revision the drafts were staged against, when known.
+     * @returns true for Host acceptance, false for refusal, after any recovery read.
+     */
+    mutate(ops: readonly SettingsFormPathOp[], expectedRevision?: number): Promise<boolean>;
+}
+/** The write one field's staged text performs when the card is saved. */
+export type SettingsFieldWrite = {
+    kind: 'set';
+    value: unknown;
+} | {
+    kind: 'clear';
+};
+/** How one section field converts between its stored value and its draft text. */
+export interface SettingsFieldSpec {
+    /** Field name inside the namespace section. */
+    field: string;
+    /** Render a stored value as draft text; the empty string when the section carries none. */
+    format: (value: unknown) => string;
+    /**
+     * The write this draft text stages, or undefined when the text is not a
+     * value this field accepts — which blocks the save rather than discarding it.
+     */
+    parse: (text: string) => SettingsFieldWrite | undefined;
+}
+/**
+ * A control whose value is written outside the settings section. A credential
+ * literal never rides a response, so its draft has nothing to seed from: it is
+ * blank until typed, and a blank draft writes nothing.
+ */
+export interface SettingsSecretSpec {
+    /** Field name addressing this control inside the card's form. */
+    field: string;
+    /** Write the staged text; resolves to whether the Host accepted it. */
+    write: (text: string) => Promise<boolean>;
+}
+/** One field as a card's control renders it. */
+export interface SettingsFieldState {
+    /** Draft text the control renders. */
+    text: string;
+    /**
+     * Whether saving would leave a user-layer entry for this field. A staged
+     * edit answers for itself, so the badge previews the save rather than
+     * reporting a state the pending edit already contradicts.
+     */
+    overridden: boolean;
+    /** Whether the draft is not a value this field accepts, which blocks saving. */
+    invalid: boolean;
+}
+/** Form state every plugin card shares. */
+export interface SettingsFormShell {
+    /** False while the namespace is not served to this client; the card renders nothing. */
+    available: boolean;
+    /** Whether the Host document accepts writes. */
+    writable: boolean;
+    /** Whether the form holds edits that a save would write. */
+    dirty: boolean;
+    /** Whether any staged draft is invalid, which blocks the save. */
+    invalid: boolean;
+    /** Whether a save is crossing the wire. */
+    saving: boolean;
+    /** Whether the last save did not land as staged; cleared by the next edit or save. */
+    failed: boolean;
+}
+/** The write actions every plugin card's slot entry injects. */
+export interface SettingsFormActions {
+    /** Stage draft text for one field. */
+    edit: (field: string, text: string) => void;
+    /** Stage a clear, so saving lets the field re-inherit the composition layer. */
+    resetField: (field: string) => void;
+    /** Write every staged edit, then re-seed from what the Host accepted. */
+    save: () => void;
+    /** Drop every staged edit. */
+    discard: () => void;
+}
+/**
+ * A whole-number field. An empty draft clears the field; any other draft that
+ * is not a finite number blocks the save.
+ * @param field - field name inside the namespace section.
+ * @returns the field's conversion spec.
+ */
+export declare function settingsNumberField(field: string): SettingsFieldSpec;
+/**
+ * A free-text field. An empty draft clears the field, so emptying the control
+ * and saving is the same gesture as resetting it.
+ * @param field - field name inside the namespace section.
+ * @returns the field's conversion spec.
+ */
+export declare function settingsTextField(field: string): SettingsFieldSpec;
+/**
+ * Stages one card's edits over one settings namespace and writes them on save.
+ *
+ * The form publishes through a snapshot store because slot components read
+ * through a snapshot selector, while both the scope and the local drafts
+ * change underneath; every projection is rebuilt from the two together.
+ */
+export declare class SettingsFormModel<T> {
+    private readonly scope;
+    private readonly specs;
+    private readonly secretSpecs;
+    private readonly staged;
+    private readonly listeners;
+    private baseline;
+    private readonly unsubscribe;
+    private saving;
+    private failed;
+    /**
+     * @param scope - the shared configuration form for this card's namespace.
+     * @param specs - the section fields this card edits.
+     * @param secrets - the card's write-only controls, written outside the section.
+     */
+    constructor(scope: SettingsFormScope<T>, specs: SettingsFieldSpec[], secrets?: SettingsSecretSpec[]);
+    /**
+     * Publish a projection of this form, rebuilt whenever the scope or a draft changes.
+     * @param project - build the card's state from the form's current reads.
+     * @returns the store the card's component reads through its bound selector.
+     */
+    bind<S>(project: () => S): SnapshotStore<S>;
+    /**
+     * Read the card-level state: what the Host serves, and what a save would do.
+     * @returns the form state every card shares.
+     */
+    shell(): SettingsFormShell;
+    /**
+     * Read one control's state.
+     * @param field - field name of a section field or of a write-only control.
+     * @returns the draft text, whether a save would leave an override, and whether it is invalid.
+     */
+    field(field: string): SettingsFieldState;
+    /**
+     * Build the edit, reset, save, and discard actions bound to this form.
+     * @returns the actions a card's slot entry injects.
+     */
+    actions(): SettingsFormActions;
+    /**
+     * Write every staged edit, then re-seed from what the Host accepted.
+     *
+     * The Host is the only authority on whether a value was accepted — its
+     * validators own the constraints no schema can express — so the outcome is
+     * read back from the section rather than predicted here. A save that did not
+     * land keeps its drafts, so the user can correct them instead of retyping.
+     * @returns settlement after every write and the read-back.
+     */
+    save(): Promise<void>;
+    /** Release the form's accepted-value subscription. */
+    dispose(): void;
+    /**
+     * Every staged edit a save would write. An entry whose draft is not a value
+     * its field accepts carries no write: the form is still dirty, and the save
+     * refuses rather than dropping the edit.
+     * @returns the planned writes, in the order the fields were staged.
+     */
+    private plan;
+    private stage;
+    private spec;
+    private snapshotOf;
+    private sectionValue;
+    private baseValue;
+    private userLayer;
+    private stored;
+    private publish;
+}
+//# sourceMappingURL=form-model.d.ts.map

package/lib/types/use-copy-feedback.d.ts

@@ -0,0 +1,14 @@
+/** The copy-feedback hook's return: the transient flag and the copy handler. */
+export interface CopyFeedback {
+    /** True for {@link COPIED_FEEDBACK_MS} after a successful write; render the success label off it. */
+    copied: boolean;
+    /** Copy the hook's text; no-op while `copied` is still true, silent on a refused write. */
+    onCopy: () => void;
+}
+/**
+ * Copy `text` to the clipboard with one-second success feedback.
+ * @param text - the text to write on copy.
+ * @returns the `copied` flag and the `onCopy` handler.
+ */
+export declare function useCopyFeedback(text: string): CopyFeedback;
+//# sourceMappingURL=use-copy-feedback.d.ts.map

package/lib/types/useAnchoredMaxHeight.d.ts

@@ -0,0 +1,11 @@
+import type { RefObject } from 'react';
+/**
+ * Clamp a bottom-anchored overlay's max-height to the viewport.
+ * @param ref - the overlay element; a null current (overlay closed) skips measuring.
+ * @param cap - design max-height in px (the clamp never exceeds it).
+ * @param signal - re-measure trigger: pass the overlay's render state so anchor
+ *   moves (composer growth) re-fit; resize/scroll re-fit while mounted.
+ * @returns the max-height to apply inline, in px.
+ */
+export declare function useAnchoredMaxHeight(ref: RefObject<HTMLElement>, cap: number, signal: unknown): number;
+//# sourceMappingURL=useAnchoredMaxHeight.d.ts.map

package/lib/types/useAnchoredPosition.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Keep a fixed-position floating element anchored to a trigger.
+ *
+ * A portaled panel is positioned from its anchor's viewport rect, which stops
+ * being true the moment anything scrolls or the window resizes. This owns that
+ * one concern: measure the anchor, offset the panel below or above it, clamp
+ * the result inside the viewport, and re-run on scroll (capture phase, so
+ * scrollers nested inside the page are caught too), on resize, and on the
+ * panel's own size changes while the element is open.
+ * @module @qilin-agent/client-ui-primitives/useAnchoredPosition
+ */
+import { type CSSProperties, type RefObject } from 'react';
+/** Inputs for {@link useAnchoredPosition}. */
+export interface AnchoredPositionOptions {
+    /** Whether the floating element is mounted and should track its anchor. */
+    open: boolean;
+    /** The element the panel is placed from. */
+    anchorRef: RefObject<HTMLElement | null>;
+    /** The floating element, measured so the clamp uses real dimensions. */
+    panelRef: RefObject<HTMLElement | null>;
+    /** Which anchor edge the panel hangs from: below it (`bottom`, the default) or above it (`top`). */
+    side?: 'top' | 'bottom';
+    /** Distance kept between the anchor edge named by `side` and the panel. */
+    gap: number;
+    /** Distance kept between the panel and each viewport edge. */
+    margin: number;
+}
+/**
+ * Track an anchor and return the panel's fixed coordinates.
+ * @param options - the open state, the two refs, the placement side, and the gap/margin distances.
+ * @returns `left`/`top` for the panel, or `null` before the first measurement.
+ */
+export declare function useAnchoredPosition(options: AnchoredPositionOptions): CSSProperties | null;
+//# sourceMappingURL=useAnchoredPosition.d.ts.map

package/lib/types/useDismissOnOutsidePointer.d.ts

@@ -0,0 +1,11 @@
+import type { RefObject } from 'react';
+/**
+ * Close an open popover when a pointerdown lands outside its root element.
+ * @param root - element containing both the trigger and the open surface.
+ * @param open - whether the surface is showing; false detaches the listener.
+ * @param setOpen - state setter invoked with false on an outside pointerdown.
+ * @param portal - surface portaled outside the root (a `document.body` dialog)
+ * that also counts as inside; omit when the root contains the whole popover.
+ */
+export declare function useDismissOnOutsidePointer(root: RefObject<HTMLElement | null>, open: boolean, setOpen: (open: boolean) => void, portal?: RefObject<HTMLElement | null>): void;
+//# sourceMappingURL=useDismissOnOutsidePointer.d.ts.map

package/lib/types/useModalLayer.d.ts

@@ -0,0 +1,27 @@
+import type { RefObject } from 'react';
+/** Dialog and menu elements whose document order determines foreground shortcut ownership. */
+export declare const modalSelector = "[role=\"dialog\"][aria-modal=\"true\"], [role=\"menu\"]";
+/**
+ * Request closure of the foreground registered modal using its current onClose callback.
+ * A newer menu or unregistered dialog blocks dismissal of the modal behind it.
+ * @param document - product document whose modal owns the close command.
+ */
+export declare function closeTopModal(document: Document): void;
+/**
+ * Whether an anchor belongs behind the current modal and must yield keyboard input.
+ * @param anchor - local control owning the input handler.
+ * @returns true when another modal owns the foreground.
+ */
+export declare function isBehindModal(anchor: HTMLElement | null): boolean;
+/**
+ * Give only the top modal Escape and Tab ownership, then restore its previous focus.
+ * Automatic entry and return focus omit outlines; keyboard traversal retains its indicators.
+ * Controls mounted with the dialog use data-modal-autofocus for initial focus;
+ * React autoFocus runs before this layer can capture the invoking control.
+ * Local menus handle their Escape during capture before this bubble listener.
+ * @param dialog - mounted dialog element.
+ * @param open - whether this layer is active.
+ * @param onClose - top-layer Escape or application close action.
+ */
+export declare function useModalLayer(dialog: RefObject<HTMLElement | null>, open: boolean, onClose: () => void): void;
+//# sourceMappingURL=useModalLayer.d.ts.map

package/lib/types/user-text.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Display projection of reference forms in sent user text (bubble and queue
+ * rows). The logged model text remains the single truth; this is presentation
+ * only, and every part renders inline so a single-line message never breaks
+ * across lines. Four decoration sources, by precedence: the wire session form
+ * `@[label](qilin-session:...)` folds to its label; exact session labels
+ * supplied by an adjacent recall decorate their bare `@label` mention; plain
+ * `@name` word-boundary tokens decorate by shape alone; and a plain `/name`
+ * token decorates only when the caller names it — a skill the host actually
+ * loaded for that message (ui-chat reads the step's `skill-invocation`
+ * injections) or the command a command-input bubble echoes — so `/123` or a
+ * stray `/word` stays plain text. A `/name` token is whitespace-bounded like
+ * the host skill gesture (`qilin-tool-skill`): it ends at whitespace or the
+ * text end, so slash paths (`/nfs-hg/xxx`, `/plan.md`) and punctuation-glued
+ * tokens (`/plan。`) stay plain even for a loaded name.
+ */
+import type { ReactNode } from 'react';
+/** Optional navigation supplied by consumers that can preview references. */
+export interface UserTextReferences {
+    /** Open a file path decoded from an `@` mention. */
+    openFile: (path: string) => void;
+    /** Open the source of a skill loaded for this message. */
+    openSkill: (name: string) => void;
+}
+/**
+ * Split one sent text into inline plain runs and reference chips.
+ * @param text - the logged model text of the message or queue row.
+ * @param sessionLabels - exact session mention labels associated by an adjacent recall.
+ * @param slashNames - names a `/name` token may decorate as: the skills the
+ * host loaded for this message, or the command a command bubble echoes
+ * (unsent queue rows pass none).
+ * @param slashKind - the chip kind those tokens render as.
+ * @param references - optional file and skill preview actions; session and command tokens stay labels.
+ * @returns inline nodes covering the whole text.
+ */
+export declare function projectUserText(text: string, sessionLabels: readonly string[], slashNames?: readonly string[], slashKind?: 'skill' | 'command', references?: UserTextReferences): ReactNode;
+//# sourceMappingURL=user-text.d.ts.map

package/lib/user-text.module.css

@@ -0,0 +1,43 @@
+/* Inline projection of sent user text: plain runs and reference chips flow in
+   the consumer's own line box (bubble or queue row); nothing here is block.
+   White-space policy stays with the consumer: the bubble wraps with pre-wrap,
+   the queue preview keeps its single nowrap/ellipsis line. */
+
+.plainRun {
+  font-size: inherit;
+  line-height: inherit;
+}
+
+.refChip {
+  /* Plain inline, NOT inline-flex: a flex container takes its baseline from
+     its first flex item — the icon svg, which has no text baseline — so the
+     chip's label rode ~3px above the surrounding text in both surfaces. An
+     inline chip shares the consumer's baseline by construction. */
+  display: inline;
+  margin: 0 2px;
+  color: var(--qilin-alias-state-business-primary);
+  font-weight: 500;
+  white-space: nowrap;
+}
+
+/* Skill and command tokens read as code: the theme's code family at the
+   consumer's own size and line height, so the chip sits on the bubble line
+   like the plain runs around it. `@` chips keep the body face — a file or
+   session name is a label, not code. */
+.slashChip {
+  font-family: var(--qilin-font-markdown-code-font-family);
+}
+
+/* Inline reference glyphs (always ReferenceIcon svgs) ride the consumer's own
+   font: 1em keeps the glyph at the text's size in the bubble (14px + user
+   setting), the queue preview's fixed 13px line, and any future consumer — a
+   px+delta size followed only the bubble axis and left the glyph oversized in
+   the queue row. */
+.refIcon {
+  width: 1em;
+  height: 1em;
+  margin-right: 4px;
+  /* Optical centering against the text: drops the glyph below the baseline by
+     a font-relative amount, so it holds across the font axis. */
+  vertical-align: -0.125em;
+}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@qilin-agent/client-ui-primitives",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Pure React atoms for the qilin web UI: controls, icons, markdown, and JSON inspectors (zero cordis)",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-primitives"
+  },
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@shikijs/langs": "^4.3.1",
+    "@types/mdast": "^4.0.4",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "anser": "^2.3.5",
+    "clsx": "^2.0.0",
+    "diff": "^9.0.0",
+    "katex": "^0.16.47",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-math": "^3.0.0",
+    "mermaid": "11.17.2",
+    "micromark-core-commonmark": "^2.0.3",
+    "micromark-extension-gfm": "^3.0.0",
+    "micromark-extension-math": "^3.1.0",
+    "micromark-factory-space": "^2.0.1",
+    "micromark-util-character": "^2.1.1",
+    "micromark-util-classify-character": "^2.0.1",
+    "micromark-util-sanitize-uri": "^2.0.1",
+    "micromark-util-symbol": "^2.0.1",
+    "micromark-util-types": "^2.0.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "shiki": "^4.3.1",
+    "simple-icons": "16.31.0",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/client-store": "3.1.4",
+    "@qilin-agent/util-workspace-path": "3.1.4"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/**/*.css",
+    "lib/types/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }