@pieai/swimmer-ui-kit 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 2.10.0 — 2026-09-24
+
+Minor: publish the reviewed optional liquid interaction surface required by
+NerveKit's human-paced guidance, companion settings and selection comparison.
+
+- `LiquidPresence` accepts interactive guide content, an expanded review size,
+  explicit ambient motion and bounded material settings. Ordinary controls and
+  the omitted-option defaults remain unchanged.
+- Export `LiquidAnchor` and `LiquidReveal` from the existing optional leaf for
+  host-positioned surfaces. These are presentation only, not agent, credential,
+  microphone, task or persistence implementations.
+- Preserve native-dialog placement, reduced motion, visibility suspension,
+  original target hit boxes and shared rendering budgets. Final accepted model
+  results and user actions remain owned by the consuming application.
+
+This release packages the previously committed and reviewed liquid work; it
+does not replace a product's live-provider or deployment acceptance.
+
 ## 2.9.0 — 2026-09-21
 
 Minor: publish the optional liquid presence leaf for products that already own

package/dist/liquid-presence.css

@@ -1 +1 @@
-.game-ui-liquid-presence{--liquid-presence-from:var(--game-ui-secondary);--liquid-presence-to:var(--game-ui-secondary);vertical-align:middle;pointer-events:none;color:var(--game-ui-secondary);flex:none;line-height:0;display:inline-block;position:relative}.game-ui-liquid-presence>svg{width:100%;height:100%;display:block;overflow:visible}.game-ui-liquid-presence[data-activity=disabled]{opacity:.5}.game-ui-liquid-presence[data-activity=error],.game-ui-liquid-presence[data-activity=unknown]{--liquid-presence-from:var(--game-ui-warning);--liquid-presence-to:var(--game-ui-warning)}.game-ui-liquid-presence-overlay{z-index:95;pointer-events:none;color:var(--game-ui-secondary);position:fixed;inset:0;overflow:visible}.game-ui-liquid-presence-overlay>[hidden]{display:none!important}.game-ui-liquid-presence-flight,.game-ui-liquid-presence-seat{transform-origin:50%;position:absolute;top:0;left:0;overflow:visible}.game-ui-liquid-presence-flight{width:96px;height:72px}.game-ui-liquid-presence-seat{width:112px;height:56px}.game-ui-liquid-presence-label{box-sizing:border-box;border-radius:var(--game-ui-radius-control,12px);background:var(--game-ui-panel-strong);width:max-content;max-width:min(260px,100vw - 32px);color:var(--game-ui-text);box-shadow:var(--game-ui-shadow-button);font:500 13px/1.5 var(--game-ui-font-body);overflow-wrap:anywhere;text-wrap:pretty;padding:9px 14px;position:absolute;top:0;left:0}@media (prefers-reduced-motion:reduce){.game-ui-liquid-presence-flight{display:none}}@media (forced-colors:active){.game-ui-liquid-presence svg g,.game-ui-liquid-presence-overlay svg g,.game-ui-liquid-presence-overlay svg path{filter:none;fill:highlight}.game-ui-liquid-presence-label{color:canvastext;box-shadow:none;background:canvas;border:1px solid canvastext}}
+:root{--game-ui-assistance-z:96;--game-ui-liquid-reveal-bg:#050c0df0;--game-ui-liquid-reveal-solid:#101718;--game-ui-liquid-reveal-text:#f2f7f4;--game-ui-liquid-reveal-muted:#b6c7c0;--game-ui-liquid-reveal-shadow:0 22px 70px #00000038;--game-ui-liquid-reveal-backdrop:#0000003d;--game-ui-liquid-action-face:#fff8ec;--game-ui-liquid-action-ink:#403127;--game-ui-liquid-action-lip:#ae9e87;--game-ui-liquid-action-border:#dccdb9;--game-ui-liquid-field-face:#0000003d;--game-ui-liquid-material-ink:#020a08;--game-ui-liquid-material-muted:#020a08;--game-ui-liquid-material-field:#104a41;--game-ui-liquid-field-ink:#f2f7f4}.game-ui-liquid-reveal .game-ui-button--secondary{background:var(--game-ui-liquid-action-face);color:var(--game-ui-liquid-action-ink);border:1px solid var(--game-ui-liquid-action-border);--game-ui-button-lip-ink:var(--game-ui-liquid-action-lip);--game-ui-shadow-button:inset 0 1px 0 color-mix(in srgb, var(--game-ui-liquid-action-face) 90%, transparent)}.game-ui-liquid-reveal .game-ui-button:disabled{opacity:.55}.game-ui-liquid-reveal .game-ui-button--ghost{color:var(--game-ui-liquid-reveal-muted)}.game-ui-liquid-reveal{isolation:isolate;min-width:0;color:var(--game-ui-liquid-reveal-text);font-family:var(--game-ui-font-body);border-radius:32px;position:relative}.game-ui-liquid-reveal:before{content:"";z-index:-1;background:var(--game-ui-liquid-reveal-bg);backdrop-filter:blur(8px);box-shadow:var(--game-ui-liquid-reveal-shadow);pointer-events:none;border-radius:27px;position:absolute;inset:6px}.game-ui-liquid-reveal-content{z-index:1;min-width:0;padding:12px;position:relative}.game-ui-liquid-reveal[data-reveal-surface=material]{--game-ui-liquid-reveal-text:var(--game-ui-liquid-material-ink);--game-ui-liquid-reveal-muted:var(--game-ui-liquid-material-muted);--game-ui-liquid-field-face:var(--game-ui-liquid-material-field)}.game-ui-liquid-reveal[data-reveal-surface=material]:before{backdrop-filter:none;background:0 0}.game-ui-liquid-reveal[data-reveal-surface=material][data-reveal-motion=preparing] .game-ui-liquid-reveal-content,.game-ui-liquid-reveal[data-reveal-surface=material][data-reveal-motion=preparing] .game-ui-liquid-reveal-ink{opacity:0}.game-ui-liquid-reveal[data-reveal-surface=material]:is([data-reveal-motion=preparing],[data-reveal-motion=drawing]):before{box-shadow:none}.game-ui-liquid-reveal[data-reveal-filter=flat]:before{backdrop-filter:none;background:var(--game-ui-liquid-reveal-solid)}.game-ui-liquid-reveal-ink{pointer-events:none;position:absolute;inset:0;overflow:visible}.game-ui-liquid-reveal[data-reveal-variant=input]{border-radius:36px}.game-ui-liquid-reveal[data-reveal-variant=input]:before{border-radius:30px}@media (forced-colors:active){.game-ui-liquid-reveal{color:canvastext;border:2px solid canvastext}.game-ui-liquid-reveal:before{box-shadow:none;backdrop-filter:none;background:canvas}.game-ui-liquid-reveal[data-reveal-surface=material]{--game-ui-liquid-reveal-text:CanvasText;--game-ui-liquid-reveal-muted:CanvasText;--game-ui-liquid-field-ink:CanvasText;--game-ui-liquid-field-face:Canvas}.game-ui-liquid-reveal[data-reveal-surface=material]:before{background:canvas}.game-ui-liquid-reveal-ink{display:none}}.game-ui-liquid-presence{--liquid-presence-from:var(--game-ui-secondary);--liquid-presence-to:var(--game-ui-secondary);vertical-align:middle;pointer-events:none;color:var(--game-ui-secondary);flex:none;line-height:0;display:inline-block;position:relative}.game-ui-liquid-presence>svg{width:100%;height:100%;display:block;overflow:visible}.game-ui-liquid-presence[data-activity=disabled]{opacity:.5}.game-ui-liquid-presence[data-activity=error],.game-ui-liquid-presence[data-activity=unknown]{--liquid-presence-from:var(--game-ui-warning);--liquid-presence-to:var(--game-ui-warning)}.game-ui-liquid-presence-overlay{z-index:95;pointer-events:none;color:var(--game-ui-secondary);position:fixed;inset:0;overflow:visible}.game-ui-liquid-presence-overlay>[hidden]{display:none!important}.game-ui-liquid-presence-flight,.game-ui-liquid-presence-seat{transform-origin:50%;position:absolute;top:0;left:0;overflow:visible}.game-ui-liquid-presence-flight{width:96px;height:72px}.game-ui-liquid-presence-seat{width:112px;height:56px}.game-ui-liquid-presence-label{box-sizing:border-box;border-radius:var(--game-ui-radius-control,12px);background:var(--game-ui-panel-strong);width:max-content;max-width:min(260px,100vw - 32px);color:var(--game-ui-text);box-shadow:var(--game-ui-shadow-button);font:500 13px/1.5 var(--game-ui-font-body);overflow-wrap:anywhere;text-wrap:pretty;padding:9px 14px;position:absolute;top:0;left:0}.game-ui-liquid-presence-label--guide{overscroll-behavior:contain;pointer-events:auto;text-wrap:wrap;border-radius:16px;width:300px;max-width:calc(100vw - 32px);max-height:min(300px,42dvh);padding:16px;overflow:auto}.game-ui-liquid-presence-label--expanded{flex-direction:column;width:420px;max-height:min(560px,65dvh);display:flex}@media (prefers-reduced-motion:reduce){.game-ui-liquid-presence-flight{display:none}}@media (forced-colors:active){.game-ui-liquid-presence svg g,.game-ui-liquid-presence-overlay svg g,.game-ui-liquid-presence-overlay svg path{filter:none;fill:highlight}.game-ui-liquid-presence-label{color:canvastext;box-shadow:none;background:canvas;border:1px solid canvastext}}.game-ui-liquid-anchor{z-index:var(--game-ui-assistance-z,95);width:max-content}

package/dist/liquid-presence.d.ts

@@ -1,4 +1,19 @@
 import { JSX } from 'react';
+import { Placement } from '@floating-ui/react';
+import { ReactNode } from 'react';
+import { RefObject } from 'react';
+
+/** Positions an outlet beside a host-owned body, never positions the body itself.
+ * Reuses Floating UI and the source's native dialog; no second modal manager. */
+export declare function LiquidAnchor({ source, children, placement, onBoundsChange, }: LiquidAnchorProps): JSX.Element | null;
+
+export declare interface LiquidAnchorProps {
+    source: RefObject<HTMLElement | null>;
+    children: ReactNode;
+    placement?: Placement;
+    /** A layout observation for host scene-label avoidance, never permission. */
+    onBoundsChange?(rect: LiquidPresenceRect | null): void;
+}
 
 /** A liquid body and its visual gesture. It never creates a model, acquires
  * media, clicks an app control, or interprets animation as a task receipt. */
@@ -13,6 +28,15 @@ export declare interface LiquidPresenceProps {
     target?: LiquidPresenceTarget | null;
     /** True disables travel but never removes the target explanation. */
     reducedMotion?: boolean;
+    /** Explicit host opt-in. A quiet living contour, never an audio observation.
+     * The ordinary component stays still when omitted. */
+    idleMotion?: 'still' | 'breathe';
+    /** Material flow only, not task or guidance duration. Clamped to 0.5..1.5. */
+    motionSpeed?: number;
+    /** Contour/speech detail, clamped to 0.25..1.25. Hit targets never change. */
+    motionIntensity?: number;
+    /** Small liquid satellites during observed speech; never during idle. */
+    splashes?: boolean;
     /** Actual amplitude only. Null/invalid values mean unavailable, not mock audio. */
     levelRef?: {
         readonly current: number | null;
@@ -20,6 +44,14 @@ export declare interface LiquidPresenceProps {
     colorFrom?: string;
     colorTo?: string;
     className?: string;
+    /** Human-paced explanation at the destination. The host owns its controls;
+     * this stays until explicit dismissal/target loss, not a reading deadline. */
+    guideContent?: ReactNode;
+    /** Expanded for review/editing content; still bounded to the visible viewport. */
+    guideSize?: 'compact' | 'expanded';
+    /** Pointing at a button dismisses by default. Editor-attached assistance may
+     * opt out so selecting/typing never discards the user's comparison draft. */
+    dismissOnTargetClick?: boolean;
     /** Visual dismissal only; never wire this to task cancellation. */
     onDismiss?(reason: 'dismissed' | 'unavailable' | 'expired'): void;
 }
@@ -41,4 +73,29 @@ export declare interface LiquidPresenceTarget {
     contextElement?: Element | null;
 }
 
+/** One finite material gesture, not a window, microphone, state machine or
+ * another orb. The real HTML stays still and usable while the perimeter draws.
+ * Uses the SAME opaque fill, goo/gloss and budget as LiquidPresence. */
+export declare function LiquidReveal({ children, source, revealKey, variant, surface, reducedMotion, idleMotion, colorFrom, colorTo, motionIntensity, motionSpeed, className, }: LiquidRevealProps): JSX.Element;
+
+export declare interface LiquidRevealProps {
+    children: ReactNode;
+    /** Real launcher geometry. Omit for a static inline resource surface. */
+    source?: RefObject<HTMLElement | null>;
+    /** A new explicitly requested presentation, never a token/stream revision. */
+    revealKey?: string;
+    variant?: 'content' | 'input';
+    /** Same liquid colour through the whole face. Dark retains the earlier style. */
+    surface?: 'material' | 'dark';
+    reducedMotion?: boolean;
+    /** Optional slow perimeter flow. Caller must offer a persistent pause control. */
+    idleMotion?: 'still' | 'breathe';
+    /** Same palette as the source; appearance only, never provider state. */
+    colorFrom?: string;
+    colorTo?: string;
+    motionIntensity?: number;
+    motionSpeed?: number;
+    className?: string;
+}
+
 export { }