@nomix-ai/nomix-harness 0.2.4 → 0.2.6

package/dist/kernel/client-ui-primitives/lib/invariant.js

@@ -22,3 +22,5 @@ const install = () => {};
 const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
 //#endregion
 export { apply, inject, name };
+
+//# sourceMappingURL=invariant.js.map

package/dist/kernel/client-ui-primitives/lib/markdown/CodeBlock.module.css

@@ -0,0 +1,96 @@
+/* Visual baseline: deepsuite `@deepseek/md` code-block.css. Highlight colors
+   stay on the existing shiki `--shiki-*` sheet (not Prism highlight.css). */
+
+.block {
+  --dsl-code-block-banner-background-color: var(--dsw-alias-markdown-code-block-banner);
+  --dsl-code-block-border-radius: 12px;
+  --dsl-code-block-banner-font: var(--dsw-font-xs-13);
+  --dsl-code-block-content-font: var(--dsw-font-markdown-code-block);
+
+  position: relative;
+  margin: 16px 0;
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-markdown-code-block);
+  border-radius: var(--dsl-code-block-border-radius);
+}
+
+.block:not(:last-child) {
+  margin-bottom: 11px;
+}
+
+.bannerWrap {
+  position: sticky;
+  top: 0;
+  z-index: 6;
+  background-color: var(--dsw-alias-bg-base);
+  border-top-left-radius: var(--dsl-code-block-border-radius);
+  border-top-right-radius: var(--dsl-code-block-border-radius);
+}
+
+.banner {
+  background: var(--dsl-code-block-banner-background-color);
+  padding: 9px 14px;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 12px;
+  font: var(--dsl-code-block-banner-font);
+  border-top-left-radius: var(--dsl-code-block-border-radius);
+  border-top-right-radius: var(--dsl-code-block-border-radius);
+}
+
+.infostring {
+  color: var(--dsw-alias-label-primary);
+  font-family: var(--ds-font-family-code);
+  font-size: 12px;
+  line-height: 18px;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.action {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+.copyButton {
+  background-color: rgb(255 255 255 / 0);
+  border: none;
+  padding: 0;
+  margin: 0;
+  color: inherit;
+  cursor: pointer;
+  font: inherit;
+}
+
+.block :where(pre) {
+  font: var(--dsl-code-block-content-font);
+  padding: 16px;
+  margin: 0 !important;
+  overflow-x: auto;
+  white-space: pre-wrap;
+  word-break: break-all;
+  background: var(--dsw-alias-markdown-code-block);
+  /* Bottom radii live on <pre>: overflow:hidden on .block would kill the
+     sticky banner, and this opaque fill otherwise squares off the wrapper. */
+  border-bottom-left-radius: var(--dsl-code-block-border-radius);
+  border-bottom-right-radius: var(--dsl-code-block-border-radius);
+}
+
+/* Shiki inlines its theme background var; route it to the repo token. */
+.block :where(pre.shiki) {
+  background: var(--dsw-alias-markdown-code-block) !important;
+}
+
+.block :where(pre) code {
+  font: inherit;
+  background: none;
+  padding: 0;
+}
+
+.plain {
+  color: var(--dsw-alias-label-primary);
+}

package/dist/kernel/client-ui-primitives/lib/markdown/JsonBlock.module.css

@@ -0,0 +1,32 @@
+.root {
+  margin: 4px 0;
+}
+
+.toggle {
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-secondary);
+  padding: 2px 6px;
+  border: none;
+  background: transparent;
+  cursor: pointer;
+  border-radius: 6px;
+}
+
+.toggle:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.body {
+  margin: 4px 0 0;
+  padding: 8px;
+  max-height: 200px;
+  overflow: auto;
+  background: var(--dsw-alias-markdown-code-block);
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 6px;
+  font-family: var(--ds-font-family-code);
+  font-size: 11px;
+  line-height: 16px;
+  color: var(--dsw-alias-label-primary);
+}

package/dist/kernel/client-ui-primitives/lib/markdown/MarkdownText.module.css

@@ -0,0 +1,304 @@
+/* Visual baseline: deepsuite `@deepseek/md` markdown.css, adapted to CSS
+   Modules. Cite pills, header anchors, and thinking-small variants are
+   intentionally absent (no matching DOM). Token names match that sheet. */
+
+.markdown {
+  min-width: 0;
+  overflow-wrap: anywhere;
+  font: var(--dsw-font-markdown-base);
+  color: var(--dsw-alias-label-primary);
+}
+
+.markdown strong {
+  font-weight: 600;
+}
+
+.markdown h1 {
+  font: var(--dsw-font-markdown-h1);
+  margin: 32px 0 16px;
+}
+
+.markdown h2 {
+  font: var(--dsw-font-markdown-h2);
+  margin: 32px 0 16px;
+}
+
+.markdown h3 {
+  font: var(--dsw-font-markdown-h3);
+  margin: 32px 0 16px;
+}
+
+.markdown h4 {
+  font: var(--dsw-font-markdown-h4);
+  margin: 16px 0;
+}
+
+.markdown :where(h5, h6) {
+  font: var(--dsw-font-markdown-base-strong);
+  margin: 16px 0;
+}
+
+.markdown :where(h1, h2, h3, h4, h5, h6) strong {
+  font-weight: inherit;
+}
+
+.markdown p {
+  margin: 16px 0;
+}
+
+/* Tighten h4–h6 against a following list (design: 8px gap). */
+.markdown :where(h4, h5, h6) + :where(ul, ol) {
+  margin-top: 8px;
+}
+
+.markdown :where(h4, h5, h6):has(+ :where(ul, ol)) {
+  margin-bottom: 8px;
+}
+
+.markdown a {
+  /* deepsuite markdown.css uses brand-text (blue in newDesign); this sheet
+     keeps design-platform brand-text as near-black, so links use the blue
+     business-primary alias instead. */
+  color: var(--dsw-alias-state-business-primary);
+  transition: box-shadow var(--ds-transition-duration) var(--ds-ease-in-out);
+  position: relative;
+  text-decoration: none;
+  /* Transparent hit-area padding; literal zero-alpha only (no painted color). */
+  border-left: 3px solid rgb(255 255 255 / 0);
+  border-right: 3px solid rgb(255 255 255 / 0);
+  border-top: 2px solid rgb(255 255 255 / 0);
+  border-bottom: 2px solid rgb(255 255 255 / 0);
+  margin-left: -3px;
+  margin-right: -3px;
+}
+
+.markdown a:hover,
+.markdown a:focus {
+  outline: none;
+  text-decoration: underline var(--dsw-alias-state-business-primary);
+}
+
+.markdown a:focus-visible {
+  box-shadow: 0 0 0 2px var(--dsw-alias-state-business-primary);
+}
+
+.markdown :where(ul, ol) {
+  margin: 16px 0;
+  padding-left: 18px;
+}
+
+.markdown li:not(:first-child) {
+  margin-top: 6px;
+}
+
+.markdown li > :where(ul, ol) {
+  margin-top: 4px;
+}
+
+.markdown li::marker {
+  line-height: 28px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+/* Nested ol under ul/ol: markers inside (models sometimes emit this shape). */
+.markdown :where(ul, ol) ol {
+  list-style-position: inside;
+  padding-left: 0;
+}
+
+.markdown :where(ul, ol) ol li p {
+  display: inline;
+}
+
+.markdown li > p {
+  margin: 8px 0;
+}
+
+.markdown li > *:first-child {
+  margin-top: 0;
+}
+
+/* Keep list-nested code-block vertical margins (design: +4px vs other last children). */
+.markdown li > *:last-child:not(:global(.md-code-block)) {
+  margin-bottom: 0;
+}
+
+.markdown hr {
+  display: block;
+  border: none;
+  height: 1px;
+  margin: 32px 0;
+  background: var(--dsw-alias-border-l2);
+}
+
+.markdown blockquote {
+  border-left: 2px solid var(--dsw-alias-label-caption);
+  margin: 16px 0 0;
+  padding-left: 14px;
+}
+
+.markdown pre {
+  margin: 16px 0;
+  font-family: var(--ds-font-family-code);
+  overflow: auto;
+}
+
+.markdown :not(pre) > code {
+  display: inline-flex;
+  align-items: center;
+  box-sizing: border-box;
+  font: var(--dsw-font-markdown-code);
+  font-family: var(--ds-font-family-code);
+  font-size: 0.875em !important;
+  background-color: var(--dsw-alias-markdown-inline-code);
+  border-radius: 6px;
+  padding: 0 5px;
+}
+
+.markdown :where(h1, h2, h3, h4, h5, h6) code {
+  font: inherit;
+  font-family: var(--ds-font-family-code);
+}
+
+.markdown :global(.katex-display) {
+  max-width: 100%;
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+
+.markdown input[type='checkbox'] {
+  margin: 0 8px 0 0;
+  accent-color: var(--dsw-alias-label-secondary);
+}
+
+.tableScroll {
+  max-width: 100%;
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+}
+
+/* Wide tables reveal their horizontal bar on hover (or keyboard focus)
+   instead of keeping it painted. Chromium never repaints state-conditioned
+   scrollbar STYLES (neither hover-conditioned `::-webkit-scrollbar*` rules
+   nor a :hover `scrollbar-color` change reaches the painted bar), so the
+   toggle is `overflow-x` itself — a layout change repaints reliably. The
+   resting padding matches the themed bar's height, so on an overflowing
+   table the appearing bar exactly replaces it and nothing below shifts.
+   Wheel and trackpad scrolling need the pointer over the table, which is
+   already the hover that re-enables `auto`. */
+.tableScroll:global(.md-table-wide) {
+  overflow-x: hidden;
+  padding-bottom: var(--nomix-scrollbar-width, 8px);
+}
+
+.tableScroll:global(.md-table-wide):hover,
+.tableScroll:global(.md-table-wide):focus-visible {
+  overflow-x: auto;
+  padding-bottom: 0;
+}
+
+/* Chromium keyboard-focuses scrollable containers by default; the ring uses
+   the sheet's link focus color. */
+.tableScroll:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--dsw-alias-state-business-primary);
+}
+
+/* Many-column tables (the renderer's `md-table-wide` hook) keep their
+   natural width and scroll inside the wrapper; a hosting layout may widen
+   the wrapper through the hook (deepsuite chat TableWrapper parity). */
+.tableScroll table {
+  border-collapse: collapse;
+  width: max-content;
+  max-width: max-content;
+}
+
+/* Tables under four columns, and any table inside a blockquote, fill the
+   column instead: cells wrap down to their minimum readable width, and the
+   wrapper's scroll only remains for the below-floor case (deepsuite chat
+   parity: `.wrapper:not(:has(th:nth-child(4), td:nth-child(4)))`). */
+.tableFill table {
+  width: 100%;
+  max-width: none;
+}
+
+.tableScroll th {
+  text-align: start;
+  padding: 10px 16px;
+  border-bottom: 1px solid var(--dsw-alias-border-l3);
+  border-top: none;
+  font: var(--dsw-font-markdown-table-head);
+  max-width: 320px;
+  max-width: min(30vw, 320px);
+  min-width: 100px;
+}
+
+.tableScroll td {
+  padding: 10px 16px;
+  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  font: var(--dsw-font-markdown-table);
+  max-width: 320px;
+  max-width: min(30vw, 320px);
+  min-width: 100px;
+}
+
+.tableScroll th:first-child,
+.tableScroll td:first-child {
+  padding-left: 0;
+}
+
+.tableScroll td:last-child {
+  padding-right: 0;
+}
+
+.tableScroll table code {
+  font-size: 13px;
+}
+
+.markdown > *:first-child,
+.markdown p:first-child {
+  margin-top: 0 !important;
+}
+
+.markdown > *:last-child,
+.markdown p:last-child {
+  margin-bottom: 0 !important;
+}
+
+.imageAlt {
+  color: var(--dsw-alias-label-tertiary);
+  font-style: italic;
+}
+
+.image {
+  display: block;
+  width: auto;
+  max-width: 100%;
+  height: auto;
+  margin: 0;
+  border-radius: 8px;
+  background: var(--dsw-alias-bg-base);
+  object-fit: contain;
+}
+
+/* Inline file mention: the same link language this sheet gives anchors (and
+   thereby URL-promoted inline code) — link-blue at rest, underline only on
+   hover/focus. An underline at rest reads badly inside the code chip, where
+   it collides with monospace descenders and the pill background. */
+.fileMention {
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  font: inherit;
+  color: var(--dsw-alias-state-business-primary);
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.fileMention:hover,
+.fileMention:focus {
+  outline: none;
+  text-decoration: underline var(--dsw-alias-state-business-primary);
+  text-underline-offset: 3px;
+}

package/dist/kernel/client-ui-primitives/lib/markdown/MessageText.module.css

@@ -0,0 +1,9 @@
+.text {
+  white-space: pre-wrap;
+  word-break: break-word;
+  /* Font metrics inherit from the consumer's container (bubble 16/24,
+     assistant flow 16/28) — a generic text primitive must not pin its own
+     size, or every consumer's line grid breaks (44px bubble spec regression). */
+  font-size: inherit;
+  line-height: inherit;
+}

package/dist/kernel/client-ui-primitives/lib/types/BrandWordmark.d.ts

@@ -1,9 +1,15 @@
 import type { IconProps } from './icons/props.ts';
+/** Display options for the Nomix brand wordmark. */
+export interface BrandWordmarkProps extends IconProps {
+    /** Whether to include the leading Nomix mark; defaults to true. */
+    includeMark?: boolean | undefined;
+}
 /**
  * Render the Nomix Harness brand wordmark.
  * @param props.size - height in px (default 24).
  * @param props.className - extra class for layout placement.
+ * @param props.includeMark - whether to include the leading Nomix mark.
  * @returns the decorative logo, product name, and Harness badge.
  */
-export declare function BrandWordmark({ size, className }: IconProps): import("react").JSX.Element;
+export declare function BrandWordmark({ size, className, includeMark }: BrandWordmarkProps): import("react").JSX.Element;
 //# sourceMappingURL=BrandWordmark.d.ts.map

package/dist/kernel/client-ui-primitives/lib/types/BrandWordmark.js

@@ -3,9 +3,11 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Render the Nomix Harness brand wordmark.
  * @param props.size - height in px (default 24).
  * @param props.className - extra class for layout placement.
+ * @param props.includeMark - whether to include the leading Nomix mark.
  * @returns the decorative logo, product name, and Harness badge.
  */
-export function BrandWordmark({ size = 24, className }) {
-    return (_jsxs("svg", { width: (size * 148) / 24, height: size, className: className, viewBox: "0 0 148 24", "aria-hidden": "true", children: [_jsx("image", { href: "/nomix-logo.jpg", width: "24", height: "24" }), _jsx("text", { x: "31", y: "17.5", fill: "currentColor", fontFamily: "Arial, sans-serif", fontSize: "17", fontWeight: "650", letterSpacing: "-0.35", children: "Nomix" }), _jsx("rect", { x: "84", y: "5", width: "62", height: "15", rx: "2.5", fill: "currentColor" }), _jsx("text", { x: "90", y: "15.5", fill: "var(--dsw-alias-label-primary-inverted)", fontFamily: "Arial, sans-serif", fontSize: "9", fontWeight: "700", letterSpacing: "0.5", children: "HARNESS" })] }));
+export function BrandWordmark({ size = 24, className, includeMark = true }) {
+    const width = includeMark ? 148 : 117;
+    return (_jsxs("svg", { width: (size * width) / 24, height: size, className: className, viewBox: includeMark ? '0 0 148 24' : '31 0 117 24', "aria-hidden": "true", children: [includeMark && _jsx("image", { href: "/nomix-logo.jpg", width: "24", height: "24" }), _jsx("text", { x: "31", y: "17.5", fill: "currentColor", fontFamily: "Arial, sans-serif", fontSize: "17", fontWeight: "650", letterSpacing: "-0.35", children: "Nomix" }), _jsx("rect", { x: "84", y: "5", width: "62", height: "15", rx: "2.5", fill: "currentColor" }), _jsx("text", { x: "90", y: "15.5", fill: "var(--dsw-alias-label-primary-inverted)", fontFamily: "Arial, sans-serif", fontSize: "9", fontWeight: "700", letterSpacing: "0.5", children: "HARNESS" })] }));
 }
 //# sourceMappingURL=BrandWordmark.js.map

package/dist/kernel/client-ui-primitives/lib/types/index.d.ts

@@ -12,6 +12,8 @@ export { Input } from './Input.tsx';
 export { Menu } from './Menu.tsx';
 export type { MenuEntry, MenuItem, MenuSeparator, MenuLabel } from './Menu.tsx';
 export { useAnchoredMaxHeight } from './useAnchoredMaxHeight.ts';
+export { useAnchoredPosition } from './useAnchoredPosition.ts';
+export type { AnchoredPositionOptions } from './useAnchoredPosition.ts';
 export { useDismissOnOutsidePointer } from './useDismissOnOutsidePointer.ts';
 export { HoverCard } from './HoverCard.tsx';
 export { Modal } from './Modal.tsx';
@@ -19,8 +21,9 @@ export { OnboardingSurface } from './OnboardingSurface.tsx';
 export { RiskConfirmation } from './RiskConfirmation.tsx';
 export type { RiskConfirmationProps } from './RiskConfirmation.tsx';
 export { ConnectionBanner } from './ConnectionBanner.tsx';
-export { NOMIX_LOGO_PATH, NomixLogo } from './NomixLogo.tsx';
+export { NomixLogo } from './NomixLogo.tsx';
 export { BrandWordmark } from './BrandWordmark.tsx';
+export type { BrandWordmarkProps } from './BrandWordmark.tsx';
 export { Tooltip } from './Tooltip.tsx';
 export type { TooltipSide } from './Tooltip.tsx';
 export { Toast } from './Toast.tsx';

package/dist/kernel/client-ui-primitives/lib/types/index.js

@@ -8,13 +8,14 @@ export { Pill } from "./Pill.js";
 export { Input } from "./Input.js";
 export { Menu } from "./Menu.js";
 export { useAnchoredMaxHeight } from "./useAnchoredMaxHeight.js";
+export { useAnchoredPosition } from "./useAnchoredPosition.js";
 export { useDismissOnOutsidePointer } from "./useDismissOnOutsidePointer.js";
 export { HoverCard } from "./HoverCard.js";
 export { Modal } from "./Modal.js";
 export { OnboardingSurface } from "./OnboardingSurface.js";
 export { RiskConfirmation } from "./RiskConfirmation.js";
 export { ConnectionBanner } from "./ConnectionBanner.js";
-export { NOMIX_LOGO_PATH, NomixLogo } from "./NomixLogo.js";
+export { NomixLogo } from "./NomixLogo.js";
 export { BrandWordmark } from "./BrandWordmark.js";
 export { Tooltip } from "./Tooltip.js";
 export { Toast } from "./Toast.js";

package/dist/kernel/client-ui-primitives/lib/types/invariant.d.ts

@@ -2,7 +2,7 @@
  * Package-owned invariant companion for `@nomix-ai/nomix-client-ui-primitives`.
  * @module @nomix-ai/nomix-client-ui-primitives/invariant
  */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 /** Cordis companion plugin name. */
 export declare const name = "client-ui-primitives-invariant";
 /** Service required before the companion can reserve package ownership. */

package/dist/kernel/client-ui-primitives/lib/types/markdown/render.d.ts

@@ -71,6 +71,8 @@ export interface MarkdownRenderContext {
     readonly streaming: boolean;
     /** Localized fence copy-button labels. */
     readonly codeLabels: MarkdownCodeLabels | undefined;
+    /** Inside a blockquote's children: tables there always fill the quote's width. */
+    readonly inBlockquote?: boolean;
     /** Inline-code file mentions; absent wherever no opener vocabulary exists. */
     readonly fileMentions: MarkdownFileMentions | undefined;
     /** Inside an anchor's children: interactive mentions must not nest there. */

package/dist/kernel/client-ui-primitives/lib/types/markdown/render.js

@@ -17,6 +17,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * may add node types this renderer has no mapping for.
  */
 import { Fragment, createElement } from 'react';
+import clsx from 'clsx';
 import { normalizeUri } from 'micromark-util-sanitize-uri';
 import { CodeBlock } from "./CodeBlock.js";
 import { renderTexToReact } from "./katex.js";
@@ -137,7 +138,7 @@ function renderNode(node, key, context) {
         case 'heading':
             return createElement(`h${node.depth}`, { key }, ...renderChildren(node.children, context));
         case 'blockquote':
-            return (_jsx("blockquote", { children: wrapBlockChildren(renderChildren(node.children, context).filter(child => child !== null), true) }, key));
+            return (_jsx("blockquote", { children: wrapBlockChildren(renderChildren(node.children, { ...context, inBlockquote: true }).filter(child => child !== null), true) }, key));
         case 'thematicBreak':
             return _jsx("hr", {}, key);
         case 'break':
@@ -281,7 +282,14 @@ function renderListItem(item, loose, key, context) {
 function renderTable(node, key, context) {
     const align = node.align ?? null;
     const [headRow, ...bodyRows] = node.children;
-    return (_jsx("div", { className: css.tableScroll, children: _jsxs("table", { children: [headRow !== undefined && _jsx("thead", { children: renderTableRow(headRow, 'th', align, 0, context) }), bodyRows.length > 0 && (_jsx("tbody", { children: bodyRows.map((row, index) => renderTableRow(row, 'td', align, index + 1, context)) }))] }) }, key));
+    const columns = align === null ? headRow?.children.length ?? 0 : align.length;
+    // Four or more columns read as a comparison matrix: the block keeps the
+    // table at natural width and exposes the stable `md-table-wide` hook so a
+    // hosting layout (the chat transcript) can widen it past the message
+    // column. Narrower tables — and any table inside a blockquote — fill the
+    // column and wrap instead (deepsuite chat TableWrapper parity).
+    const wide = columns >= 4 && context.inBlockquote !== true;
+    return (_jsx("div", { className: clsx(css.tableScroll, wide ? 'md-table-wide' : css.tableFill), tabIndex: wide ? 0 : undefined, children: _jsxs("table", { children: [headRow !== undefined && _jsx("thead", { children: renderTableRow(headRow, 'th', align, 0, context) }), bodyRows.length > 0 && (_jsx("tbody", { children: bodyRows.map((row, index) => renderTableRow(row, 'td', align, index + 1, context)) }))] }) }, key));
 }
 function renderTableRow(row, cellTag, align, key, context) {
     // With column alignment present, every row renders exactly one cell per

package/dist/kernel/client-ui-primitives/lib/types/useAnchoredPosition.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 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 @nomix-ai/nomix-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>;
+    /** Distance kept between the anchor's bottom edge and the panel's top. */
+    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, 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/dist/kernel/client-ui-primitives/lib/types/useAnchoredPosition.js

@@ -0,0 +1,69 @@
+/**
+ * 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 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 @nomix-ai/nomix-client-ui-primitives/useAnchoredPosition
+ */
+import { useLayoutEffect, useState } from 'react';
+/**
+ * Track an anchor and return the panel's fixed coordinates.
+ * @param options - the open state, the two refs, and the gap/margin distances.
+ * @returns `left`/`top` for the panel, or `null` before the first measurement.
+ */
+export function useAnchoredPosition(options) {
+    const { open, anchorRef, panelRef, gap, margin } = options;
+    const [position, setPosition] = useState(null);
+    useLayoutEffect(() => {
+        if (!open) {
+            setPosition(null);
+            return;
+        }
+        const place = () => {
+            /* v8 ignore start -- geometry read from real layout: jsdom reports zero
+               offset sizes, so the positive-size clamp arms are exercised by browser
+               scenarios rather than unit tests. */
+            const rect = anchorRef.current?.getBoundingClientRect();
+            if (rect === undefined)
+                return;
+            const panel = panelRef.current;
+            const width = panel?.offsetWidth ?? 0;
+            const height = panel?.offsetHeight ?? 0;
+            let left = rect.left;
+            let top = rect.bottom + gap;
+            if (width > 0)
+                left = Math.min(Math.max(left, margin), window.innerWidth - width - margin);
+            if (height > 0)
+                top = Math.min(Math.max(top, margin), window.innerHeight - height - margin);
+            /* v8 ignore stop */
+            setPosition({ left, top });
+        };
+        // The first run measures the panel in the same commit that opened it, so
+        // the clamp uses real dimensions before anything paints.
+        place();
+        window.addEventListener('scroll', place, true);
+        window.addEventListener('resize', place);
+        // The panel's own height changes without either event — a status line
+        // appearing inside it, or a `resize: vertical` textarea dragged taller —
+        // and a stale clamp would let a panel near the bottom edge cross the
+        // margin it is supposed to respect. The guard keeps the hook usable where
+        // `ResizeObserver` is absent, which is how jsdom runs.
+        const panel = panelRef.current;
+        let observer = null;
+        if (typeof ResizeObserver !== 'undefined' && panel !== null) {
+            observer = new ResizeObserver(place);
+            observer.observe(panel);
+        }
+        return () => {
+            observer?.disconnect();
+            window.removeEventListener('scroll', place, true);
+            window.removeEventListener('resize', place);
+        };
+    }, [open, anchorRef, panelRef, gap, margin]);
+    return position;
+}
+//# sourceMappingURL=useAnchoredPosition.js.map