akanjs 3.0.0-alpha.34 → 3.0.0-alpha.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.34",
+  "version": "3.0.0-alpha.36",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/store/agentic/StToolBuilder.ts

@@ -27,6 +27,11 @@ export interface StToolMeta {
   effect?: ToolEffect;
   confirm?: ToolConfirm;
   guard?: ToolGuard;
+  /**
+   * Set by a component that renders once per row. It is only true when the row's id rides in an argument rather
+   * than in the closure, which is what makes every row's registration interchangeable.
+   */
+  shared?: boolean;
 }
 
 interface StToolArg {
@@ -115,6 +120,7 @@ export class StToolBuilder<Args extends unknown[] = []> {
         name,
         description: spec.meta.desc,
         effect: spec.meta.effect,
+        ...(spec.meta.shared ? { shared: true } : {}),
         parameters: StToolBuilder.parametersOf(spec.args),
         
         ...(spec.meta.confirm === undefined && !name.startsWith("remove")

package/store/agentic/formFields.ts

@@ -174,6 +174,18 @@ export class FormFields {
     return field.arrDepth > 0 || (field.modelRef as unknown) === Map || !!FormFields.#scalarModel(field);
   }
 
+  /**
+   * The embedded model an array field's rows are, or null for every other field.
+   *
+   * This is the one shape where writing the whole array is a hazard rather than an inconvenience: the agent has to
+   * echo every row it is *not* changing, `checked` validates types and not values, so one mistyped row it was never
+   * asked to touch is written silently. A relation array is excluded — its rows travel as ids, which are the payload
+   * and are refused by name when wrong — and so is an array of primitives, for the same reason.
+   */
+  static rowModelOf(field: ConstantField) {
+    return field.arrDepth > 0 ? FormFields.#scalarModel(field) : null;
+  }
+
   static #scalarModel(field: ConstantField) {
     const modelRef = field.modelRef as unknown as Cls;
     if (field.enum || PrimitiveRegistry.has(modelRef)) return null;

package/store/agentic/index.ts

@@ -4,5 +4,6 @@ export * from "./readableValue";
 export * from "./StToolBuilder";
 export * from "./useFieldTool";
 export * from "./useFormTools";
+export * from "./useRelationFieldTool";
 export * from "./useStExpose";
 export * from "./useStState";

package/store/agentic/useFieldTool.ts

@@ -1,9 +1,93 @@
 "use client";
+import { capitalize } from "akanjs/common";
+import type { JsonSchema, ToolEntry } from "../../vendor/use-agentic";
 import { useScopePath, useSurface } from "../../vendor/use-agentic";
 import { actionTagOf } from "../actionTag";
+import { formSetterNames } from "../formSetterNames";
 
 import { useEffect, useRef } from "../hooks";
-import { FormFields } from "./formFields";
+import { StoreRegistry } from "../storeRegistry";
+import { type FormFieldRef, FormFields } from "./formFields";
+
+/**
+ * A control's `transform` is what it does to every value a person types, so an agent's write goes through it too —
+ * otherwise a `Field.Phone` stores `010-1234-5678` for the person and the raw digits for the agent. It normalizes
+ * one scalar, so an array-valued control (`TextList`, `Tags`, `DoubleNumber`) applies it per element. A cleared
+ * nullable field stays null: a normalizer written for a value would turn it into one.
+ */
+const normalized = (value: unknown, transform: unknown): unknown => {
+  if (typeof transform !== "function" || value === null) return value;
+  const apply = transform as (input: unknown) => unknown;
+  return Array.isArray(value) ? value.map((item) => apply(item)) : apply(value);
+};
+
+const dispatcherOf = (action: string) =>
+  StoreRegistry.instance.do[action] as ((...args: unknown[]) => unknown) | undefined;
+
+const rowsOf = (ref: FormFieldRef): unknown[] => {
+  const form = StoreRegistry.instance.get()[`${ref.refName}Form`] as { [key: string]: unknown } | undefined;
+  const rows = form?.[ref.key];
+  return Array.isArray(rows) ? rows : [];
+};
+
+/**
+ * Append and remove-by-index for an array of embedded rows, beside the whole-array setter.
+ *
+ * Not new authority: the setter this control already published can produce any array these two can, so they are
+ * strictly weaker — which is what makes deriving them from the same field sound. What they add is that neither can
+ * touch a row it was not given, so the agent stops having to retype the rows it is leaving alone.
+ *
+ * Both take a list and act atomically. Removing indices one call at a time would shift the ones not yet removed, so
+ * `sub` filters the whole set at once, the way the generated action already does.
+ *
+ * `add` appends and publishes no insert position: the `+` a person presses always appends, and the framework cannot
+ * see the `limit` an app may pass from its own `onAdd`. `addOrSub` is never published — it matches by `indexOf`, so
+ * on rows it compares by reference and every toggle would append.
+ */
+const rowEntries = (ref: FormFieldRef, arraySchema: JsonSchema): ToolEntry[] => {
+  if (!FormFields.rowModelOf(ref.field)) return [];
+  const names = formSetterNames(capitalize(ref.refName), ref.key);
+  if (!dispatcherOf(names.addFieldOnModel) || !dispatcherOf(names.subFieldOnModel)) return [];
+  return [
+    {
+      name: names.addFieldOnModel,
+      description: `Append rows to ${ref.key} on the ${ref.refName} form. Leaves every existing row untouched.`,
+      parameters: {
+        type: "object",
+        properties: { values: arraySchema },
+        required: ["values"],
+        additionalProperties: false,
+      },
+      effect: "state",
+      run: (args) => {
+        const checked = FormFields.checked(names.addFieldOnModel, "values", ref.field, args.values);
+        return dispatcherOf(names.addFieldOnModel)?.(checked);
+      },
+    },
+    {
+      name: names.subFieldOnModel,
+      description: `Remove rows of ${ref.key} from the ${ref.refName} form by their positions, counting from 0.`,
+      parameters: {
+        type: "object",
+        properties: { idxs: { type: "array", items: { type: "integer" } } },
+        required: ["idxs"],
+        additionalProperties: false,
+      },
+      effect: "state",
+      guard: (args) => {
+        const idxs = args.idxs;
+        if (!Array.isArray(idxs) || !idxs.length) return `"idxs" of ${names.subFieldOnModel} takes at least one index.`;
+        const length = rowsOf(ref).length;
+        const outside = idxs.filter(
+          (idx) => typeof idx !== "number" || !Number.isInteger(idx) || idx < 0 || idx >= length,
+        );
+        if (!outside.length) return true;
+        return `${ref.key} has ${length} ${length === 1 ? "row" : "rows"}, so ${outside.join(", ")} is out of range.`;
+      },
+      run: (args) => dispatcherOf(names.subFieldOnModel)?.(args.idxs),
+    },
+  ];
+};
 
 /**
  * Publishes the setter a form control is already holding, for exactly as long as the control is on screen.
@@ -14,27 +98,34 @@ import { FormFields } from "./formFields";
  * consequences. Publishing from the form's subscription instead would offer every field of the model, including
  * the ones this template draws no control for.
  */
-export const useFieldTool = (onChange: unknown) => {
+export const useFieldTool = (onChange: unknown, transform?: unknown) => {
   const surface = useSurface();
   const scope = useScopePath();
   const action = actionTagOf(onChange)?.action ?? null;
-  const live = useRef(onChange);
-  live.current = onChange;
+  const live = useRef({ onChange, transform });
+  live.current = { onChange, transform };
   const scopeKey = scope.join(".");
   useEffect(() => {
     if (!action) return;
     const ref = FormFields.ref(action);
     const schema = ref && FormFields.schema(ref.field);
     if (!ref || !schema) return;
-    return surface.registerTool(scope, {
-      name: action,
-      description: `Set ${ref.key} on the ${ref.refName} form.`,
-      parameters: { type: "object", properties: { value: schema }, required: ["value"], additionalProperties: false },
-      effect: "state",
-      run: (args) =>
-        (live.current as (value: unknown) => unknown)(
-          FormFields.checked(action, "value", ref.field, args.value === undefined ? null : args.value),
-        ),
-    });
+    const entries: ToolEntry[] = [
+      {
+        name: action,
+        description: `Set ${ref.key} on the ${ref.refName} form.`,
+        parameters: { type: "object", properties: { value: schema }, required: ["value"], additionalProperties: false },
+        effect: "state",
+        run: (args) => {
+          const checked = FormFields.checked(action, "value", ref.field, args.value === undefined ? null : args.value);
+          return (live.current.onChange as (value: unknown) => unknown)(normalized(checked, live.current.transform));
+        },
+      },
+      ...rowEntries(ref, schema),
+    ];
+    const registered = entries.map((entry) => surface.registerTool(scope, entry));
+    return () => {
+      for (const unregister of registered) unregister();
+    };
   }, [surface, scopeKey, action]);
 };

package/store/agentic/useRelationFieldTool.ts

@@ -0,0 +1,114 @@
+"use client";
+import { type Cls, type DataList, PrimitiveRegistry } from "akanjs/base";
+import { capitalize } from "akanjs/common";
+import { type ConstantField, ConstantRegistry } from "akanjs/constant";
+import type { JsonSchema } from "../../vendor/use-agentic";
+import { useScopePath, useSurface } from "../../vendor/use-agentic";
+import { actionTagOf } from "../actionTag";
+
+import { useEffect, useRef } from "../hooks";
+import { FormFields } from "./formFields";
+
+export interface RelationFieldSource<T extends { id: string }> {
+  /** Read live from the store rather than closed over: `load` below changes the list mid-call. */
+  read: () => DataList<T>;
+  /** Loads the options an agent never opened the dropdown to fetch. */
+  load: () => Promise<unknown> | unknown;
+  /** How one option reads to a person, so the agent can match what it sees on screen. */
+  label: (model: T) => string;
+  disabled?: boolean;
+}
+
+/** The database model a relation field points at, or null for anything else — a primitive, an enum, a scalar. */
+const relationOf = (field: ConstantField): string | null => {
+  const modelRef = field.modelRef as unknown as Cls;
+  if (field.fieldType !== "property" || field.enum || !modelRef || PrimitiveRegistry.has(modelRef)) return null;
+  const refName = ConstantRegistry.getRefName(modelRef, { allowEmpty: true });
+  return refName && ConstantRegistry.database.has(refName) ? refName : null;
+};
+
+/**
+ * The two tools a relation picker owes an agent: list the documents it can pick, then pick by id.
+ *
+ * `FormFields` publishes no schema for a relation, and it is right not to — the form holds the whole related
+ * document, so an id would need a lookup the store does not do. The picker is where that lookup lives: it holds
+ * the slice list, the loader, and the label each option renders with. So the field reaches an agent from the one
+ * component that can resolve it, which is the rule every other control follows — the control is the declaration.
+ *
+ * Listing is its own tool because loading is its own step for a person too: the options arrive when the dropdown
+ * opens, and an agent never opens it. Folding the load into the setter would leave an agent guessing ids in order
+ * to learn them from the refusal.
+ */
+export const useRelationFieldTool = <T extends { id: string }>(
+  onChange: unknown,
+  { read, load, label, disabled }: RelationFieldSource<T>,
+) => {
+  const surface = useSurface();
+  const scope = useScopePath();
+  const action = actionTagOf(onChange)?.action ?? null;
+  const live = useRef({ onChange, read, load, label });
+  live.current = { onChange, read, load, label };
+  const scopeKey = scope.join(".");
+  useEffect(() => {
+    if (!action || disabled) return;
+    const ref = FormFields.ref(action);
+    const target = ref && relationOf(ref.field);
+
+    if (!ref || !target || FormFields.schema(ref.field)) return;
+    const many = ref.field.arrDepth > 0;
+    const nullable = !!ref.field.nullable && !many;
+    const listName = `load${capitalize(ref.key)}OptionsOn${capitalize(ref.refName)}`;
+    const argName = many ? `${ref.key}Ids` : `${ref.key}Id`;
+    const id: JsonSchema = { type: "string" };
+    const options = () => live.current.read().map((model) => ({ id: model.id, label: live.current.label(model) }));
+    const idsIn = (args: Record<string, unknown>): unknown => {
+      const value = args[argName];
+      if (nullable && (value === null || value === undefined)) return [];
+      return many ? value : [value];
+    };
+    const offList = surface.registerTool(scope, {
+      name: listName,
+      description: `List the ${target}s the ${ref.refName} form can pick for ${ref.key}, loading them first. Pass an id from it to ${action}.`,
+      effect: "query",
+      run: async () => {
+        await live.current.load();
+        return options();
+      },
+    });
+    const offSet = surface.registerTool(scope, {
+      name: action,
+      description: `Set ${ref.key} on the ${ref.refName} form to ${many ? `${target}s` : `one ${target}`}, by id. Call ${listName} first for the ids.`,
+      parameters: {
+        type: "object",
+        properties: { [argName]: many ? { type: "array", items: id } : id },
+        ...(nullable ? {} : { required: [argName] }),
+        additionalProperties: false,
+      },
+      effect: "state",
+      guard: (args) => {
+        const ids = idsIn(args);
+        if (!Array.isArray(ids)) return `"${argName}" of ${action} must be an array of ids.`;
+        const list = live.current.read();
+        const missing = ids.filter((value) => typeof value !== "string" || !list.get(value));
+        if (!missing.length) return true;
+        if (!list.length) return `No ${target} is loaded yet. Call ${listName} first for the ids.`;
+        return `The ${ref.refName} form offers no ${target} ${missing.join(", ")}. It offers: ${list
+          .map((model) => `${model.id} (${live.current.label(model)})`)
+          .join(", ")}.`;
+      },
+      run: (args) => {
+        const list = live.current.read();
+        const setter = live.current.onChange as (value: unknown) => unknown;
+        const picked = (idsIn(args) as string[]).flatMap((value) => {
+          const model = list.get(value);
+          return model ? [model] : [];
+        });
+        return setter(many ? picked : (picked[0] ?? null));
+      },
+    });
+    return () => {
+      offList();
+      offSet();
+    };
+  }, [surface, scopeKey, action, disabled]);
+};

package/types/store/agentic/StToolBuilder.d.ts

@@ -6,6 +6,11 @@ export interface StToolMeta {
     effect?: ToolEffect;
     confirm?: ToolConfirm;
     guard?: ToolGuard;
+    /**
+     * Set by a component that renders once per row. It is only true when the row's id rides in an argument rather
+     * than in the closure, which is what makes every row's registration interchangeable.
+     */
+    shared?: boolean;
 }
 interface StToolArg {
     name: string;

package/types/store/agentic/formFields.d.ts

@@ -41,4 +41,13 @@ export declare class FormFields {
     static checked(action: string, path: string, field: ConstantField, value: unknown, depth?: number): unknown;
     /** A field no annotated control can ever name: its rows are written through `writeOn<Model>(path, value)`. */
     static isComposite(field: ConstantField): boolean;
+    /**
+     * The embedded model an array field's rows are, or null for every other field.
+     *
+     * This is the one shape where writing the whole array is a hazard rather than an inconvenience: the agent has to
+     * echo every row it is *not* changing, `checked` validates types and not values, so one mistyped row it was never
+     * asked to touch is written silently. A relation array is excluded — its rows travel as ids, which are the payload
+     * and are refused by name when wrong — and so is an array of primitives, for the same reason.
+     */
+    static rowModelOf(field: ConstantField): (new (...args: never[]) => unknown) | null;
 }

package/types/store/agentic/index.d.ts

@@ -4,5 +4,6 @@ export * from "./readableValue.d.ts";
 export * from "./StToolBuilder.d.ts";
 export * from "./useFieldTool.d.ts";
 export * from "./useFormTools.d.ts";
+export * from "./useRelationFieldTool.d.ts";
 export * from "./useStExpose.d.ts";
 export * from "./useStState.d.ts";

package/types/store/agentic/useFieldTool.d.ts

@@ -7,4 +7,4 @@
  * consequences. Publishing from the form's subscription instead would offer every field of the model, including
  * the ones this template draws no control for.
  */
-export declare const useFieldTool: (onChange: unknown) => void;
+export declare const useFieldTool: (onChange: unknown, transform?: unknown) => void;

package/types/store/agentic/useRelationFieldTool.d.ts

@@ -0,0 +1,27 @@
+import { type DataList } from "akanjs/base";
+export interface RelationFieldSource<T extends {
+    id: string;
+}> {
+    /** Read live from the store rather than closed over: `load` below changes the list mid-call. */
+    read: () => DataList<T>;
+    /** Loads the options an agent never opened the dropdown to fetch. */
+    load: () => Promise<unknown> | unknown;
+    /** How one option reads to a person, so the agent can match what it sees on screen. */
+    label: (model: T) => string;
+    disabled?: boolean;
+}
+/**
+ * The two tools a relation picker owes an agent: list the documents it can pick, then pick by id.
+ *
+ * `FormFields` publishes no schema for a relation, and it is right not to — the form holds the whole related
+ * document, so an id would need a lookup the store does not do. The picker is where that lookup lives: it holds
+ * the slice list, the loader, and the label each option renders with. So the field reaches an agent from the one
+ * component that can resolve it, which is the rule every other control follows — the control is the declaration.
+ *
+ * Listing is its own tool because loading is its own step for a person too: the options arrive when the dropdown
+ * opens, and an agent never opens it. Folding the load into the setter would leave an agent guessing ids in order
+ * to learn them from the refusal.
+ */
+export declare const useRelationFieldTool: <T extends {
+    id: string;
+}>(onChange: unknown, { read, load, label, disabled }: RelationFieldSource<T>) => void;

package/types/ui/Dialog/LegacyModal.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from "react";
+export interface LegacyModalProps {
+    className?: string;
+    bodyClassName?: string;
+    confirmClose?: boolean;
+    children?: ReactNode;
+    onCancel?: () => void;
+}
+/**
+ * Previous modal skin, kept for screens built around its motion: spring open/close and a drag-to-dismiss
+ * sheet on touch. New work composes {@link Modal}, which draws the same slots with no animation.
+ */
+export declare const LegacyModal: ({ className, bodyClassName, confirmClose, children, onCancel }: LegacyModalProps) => import("react").ReactPortal | null;

package/types/ui/Dialog/context.d.ts

@@ -4,6 +4,12 @@ export interface DialogContextType {
     setOpen: (open: boolean) => void;
     openDialog: () => void;
     closeDialog: () => void;
+    /**
+     * How this dialog actually dismisses, handed up by whichever surface is drawing it. `confirmClose` and
+     * `onCancel` hang off that path, so a close that only flipped `open` would skip both — which is what made an
+     * agent's close, and `Dialog.Close`, quietly different from clicking the X.
+     */
+    registerDismiss: (dismiss: (() => void) | null) => void;
     title: ReactNode;
     setTitle: (title: ReactNode) => void;
     action: ReactNode;

package/types/ui/Dialog/index.d.ts

@@ -2,6 +2,7 @@ import { type ProviderProps } from "./Provider.d.ts";
 export declare const Dialog: {
     ({ children, ...props }: ProviderProps): import("react/jsx-runtime").JSX.Element;
     Modal: ({ className, bodyClassName, confirmClose, children, onCancel }: import("./Modal.d.ts").ModalProps) => import("react").ReactPortal | null;
+    LegacyModal: ({ className, bodyClassName, confirmClose, children, onCancel }: import("./LegacyModal.d.ts").LegacyModalProps) => import("react").ReactPortal | null;
     Title: ({ children }: import("./Title.d.ts").TitleProps) => null;
     Action: ({ children }: import("./Action.d.ts").ActionProps) => null;
     Trigger: ({ className, children }: import("./Trigger.d.ts").TriggerProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/Dropdown.d.ts

@@ -12,8 +12,10 @@ export interface DropdownProps {
     buttonClassName?: string;
     /** Additional classes for the dropdown content panel. */
     dropdownClassName?: string;
+    /** Trigger edge the menu lines up with. Position is computed, so a `left-0` class cannot do this. */
+    align?: "start" | "end";
 }
-export declare const DefaultDropdown: ({ value, content, className, buttonClassName, dropdownClassName }: DropdownProps) => import("react/jsx-runtime").JSX.Element;
+export declare const DefaultDropdown: ({ value, content, className, buttonClassName, dropdownClassName, align, }: DropdownProps) => import("react/jsx-runtime").JSX.Element;
 /**
  * Dropdown. Resolves to a route-scoped override when a `page/**\/_overrides.tsx`
  * in the route's ancestry declares one, otherwise renders {@link DefaultDropdown}.

package/types/ui/LegacyModal.d.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from "react";
+export interface LegacyModalProps {
+    /** Additional classes for the modal surface. */
+    className?: string;
+    /** Optional modal title. */
+    title?: string | ReactNode;
+    /** Optional action area, usually footer buttons. */
+    action?: ReactNode;
+    /** Controlled open state. */
+    open: boolean;
+    /** Called when the modal requests closing. */
+    onCancel: () => void;
+    /** Additional classes for the content body. */
+    bodyClassName?: string;
+    children?: ReactNode;
+    /** Ask for close confirmation before dismissing. */
+    confirmClose?: boolean;
+}
+/**
+ * Previous akanjs modal skin: spring open/close and a drag-to-dismiss sheet on touch. Kept for screens
+ * built around that motion. New work uses {@link Modal}, which takes the same props with no animation,
+ * and unlike this one resolves through the `Modal` override slot.
+ */
+export declare const LegacyModal: ({ className, title, action, open, onCancel, bodyClassName, children, confirmClose, }: LegacyModalProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/Model/New.d.ts

@@ -11,6 +11,8 @@ interface NewProps<Full = any> {
     renderTitle?: ((model: {
         id: string;
     }) => string | ReactNode) | string;
+    /** Suffixes the tool this button publishes. Only a second create button for the same slice needs one. */
+    namespace?: string;
 }
-export default function New({ className, wrapperClassName, type, children, slice, modal, partial, renderTitle, }: NewProps): import("react/jsx-runtime").JSX.Element;
+export default function New({ className, wrapperClassName, type, children, slice, modal, partial, renderTitle, namespace, }: NewProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/types/ui/Model/NewWrapper.d.ts

@@ -8,6 +8,8 @@ interface NewWrapperProps<Full = any> {
     setDefault?: boolean;
     modal?: string | null;
     resets?: string[] | null;
+    /** Suffixes the tool this trigger publishes. Only a second create trigger for the same slice needs one. */
+    namespace?: string;
 }
 export default function NewWrapper<Full>({ partial, ...props }: NewWrapperProps<Full>): import("react/jsx-runtime").JSX.Element;
 export {};

package/types/ui/Model/NewWrapper_Client.d.ts

@@ -8,6 +8,7 @@ interface NewWrapperProps<Full = any> {
     setDefault?: boolean;
     modal?: string | null;
     resets?: string[] | null;
+    namespace?: string;
 }
-export declare const NewWrapper_Client: <Full>({ children, slice, partial, setDefault, className, modal, resets, }: NewWrapperProps<Full>) => import("react/jsx-runtime").JSX.Element;
+export declare const NewWrapper_Client: <Full>({ children, slice, partial, setDefault, className, modal, resets, namespace, }: NewWrapperProps<Full>) => import("react/jsx-runtime").JSX.Element;
 export {};

package/types/ui/index.d.ts

@@ -23,6 +23,7 @@ export { InfiniteScroll } from "./InfiniteScroll.d.ts";
 export { Input } from "./Input.d.ts";
 export { KeyboardAvoiding } from "./KeyboardAvoiding.d.ts";
 export { Layout } from "./Layout.d.ts";
+export { LegacyModal } from "./LegacyModal.d.ts";
 export { Link } from "./Link.d.ts";
 export { Load } from "./Load.d.ts";
 export { Loading } from "./Loading.d.ts";

package/types/ui/overlayLayer.d.ts

@@ -8,6 +8,19 @@
  * recognises its own overlays exactly, instead of guessing from how close a dialog happens to be.
  */
 export declare const OVERLAY_LAYER_ATTR = "data-akan-overlay";
+/**
+ * Stacking order for overlays that portal to `document.body`, where nesting no longer decides who is on
+ * top. A Popconfirm outranks a dropdown menu because `Model.Remove` draws one from inside a menu item,
+ * and its scrim outranks the menu so the click that answers the confirm is not also a menu selection.
+ * A Select's options stay under both: it is a field, and whatever opened over it took the click that
+ * dismisses it.
+ */
+export declare const overlayZ: {
+    readonly select: 90;
+    readonly dropdown: 100;
+    readonly popconfirmScrim: 105;
+    readonly popconfirm: 110;
+};
 /** Wrap the content a dismissable container owns, with the scope from {@link useOverlayScope}. */
 export declare const OverlayOwnerProvider: import("react").Provider<string>;
 /** Scope a dismissable container hands to its content. Nests as a `parent/child` path. */

package/types/ui/overlayPosition.d.ts

@@ -0,0 +1,28 @@
+import { type RefObject } from "react";
+export interface OverlayPosition {
+    top: number;
+    left: number;
+    /** Placed above the trigger, because there was no room below. */
+    above: boolean;
+    /** The trigger's centre relative to the panel's left edge, held clear of the panel's rounded corners. */
+    anchorOffset: number;
+    /** The trigger's own width, for a panel that lines up with the control it drops out of. */
+    anchorWidth: number;
+}
+/**
+ * Places a portalled panel against its trigger in viewport coordinates.
+ *
+ * A panel positioned inside its own tree is clipped by every `overflow` ancestor it has — the modal
+ * surface, the modal's scrolling body, a table's scroll container, the dropdown menu a row verb sits in —
+ * so overlay panels portal out to `document.body` and are placed here instead of by CSS.
+ * `position: fixed` in place would not do it either: a fixed element inside a transformed ancestor is laid
+ * out and clipped by that ancestor, and the modal surface animates a transform.
+ */
+export declare const useOverlayPosition: ({ opened, triggerRef, panelRef, align, gap, }: {
+    opened: boolean;
+    triggerRef: RefObject<HTMLElement | null>;
+    panelRef: RefObject<HTMLElement | null>;
+    align: "start" | "end";
+    /** Distance from the trigger. Raise it for a panel whose pointer sticks out past its own edge. */
+    gap?: number;
+}) => OverlayPosition | null;

package/types/vendor/use-agentic/AgenticSurface.d.ts

@@ -15,6 +15,12 @@ export declare class AgenticSurface {
     static childPath(parent: string[], id: string): string[];
     static fullName(scope: string[], name: string): string;
     subscribe(listener: () => void): () => void;
+    /**
+     * A row component registers the same name once per row. That is legal when the tool takes the row's id as an
+     * argument rather than closing over it, because every registration is then interchangeable and last-wins picks
+     * an equivalent one — `shared` is the registrant saying so, and it turns fifty rows from fifty collisions into
+     * one declaration. A shared name landing on top of a name nobody shared is still a real clash, and still warns.
+     */
     registerTool(scope: string[], entry: ToolEntry): () => void;
     registerResource(scope: string[], entry: ResourceEntry): () => void;
     openScope(parent: string[], scope: ScopeEntry): () => void;

package/types/vendor/use-agentic/types.d.ts

@@ -11,6 +11,8 @@ export interface ToolEntry {
     effect?: ToolEffect;
     confirm?: ToolConfirm;
     guard?: ToolGuard;
+    /** Declares that repeat registrations of this name are interchangeable — see `AgenticSurface.registerTool`. */
+    shared?: boolean;
     run: (args: Record<string, unknown>) => unknown;
 }
 /** One call an agent made through the surface, in the order it made them. */

package/types/webkit/index.d.ts

@@ -3,6 +3,7 @@ export { createRobotPage } from "./createRobotPage.d.ts";
 export { createSitemapPage } from "./createSitemapPage.d.ts";
 export { lazy } from "./lazy.d.ts";
 export type * from "./types.d.ts";
+export { useBodyScrollLock } from "./useBodyScrollLock.d.ts";
 export { useCamera } from "./useCamera.d.ts";
 export { useCodepush } from "./useCodepush.d.ts";
 export { useContact } from "./useContact.d.ts";

package/types/webkit/useBodyScrollLock.d.ts

@@ -0,0 +1,2 @@
+/** Hold `document.body` unscrollable while `active`. */
+export declare const useBodyScrollLock: (active: boolean) => void;