akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/ui/Toast.tsx

@@ -18,9 +18,9 @@ export interface ToastMessage {
   key: string;
   type: ToastType;
   content: ReactNode;
-  /** Seconds the message is shown before the shell starts its exit. */
+  /** Seconds shown before the exit starts. */
   duration: number;
-  /** The shell started this message's exit: play the leave animation, then call `onClosed`. */
+  /** The exit started: play the leave animation, then call `onClosed`. */
   leaving: boolean;
 }
 
@@ -43,9 +43,9 @@ const messageTone: { [key in ToastType]: { card: string; chip: string; icon: Rea
 export interface ToastItemProps {
   className?: string;
   message: ToastMessage;
-  /** Dismisses early — starts the same exit the timer would. */
+  /** Starts the same exit the timer would. */
   onClose: () => void;
-  /** Takes the message off the screen. Call it when the exit animation has finished. */
+  /** Call when the exit animation has finished. */
   onClosed: () => void;
 }
 
@@ -87,13 +87,13 @@ export const DefaultToastItem = ({ className, message, onClose, onClosed }: Toas
 
 export interface ToastProps {
   className?: string;
-  /** Oldest first, already capped by the store. A replacement showing fewer slices the list itself. */
+  /** Oldest first, already capped by the store. */
   messages: ToastMessage[];
-  /** The device's top safe area in pixels — the stack starts below it. */
+  /** In pixels; the stack starts below it. */
   topSafeArea: number;
-  /** Starts a message's exit, as the dismiss button and the elapsed timer both do. */
+  /** Starts a message's exit. */
   onClose: (key: string) => void;
-  /** Takes a message off the screen once its exit animation has finished. */
+  /** Call once a message's exit animation has finished. */
   onClosed: (key: string) => void;
 }
 
@@ -119,14 +119,7 @@ export const DefaultToast = ({ className, messages, topSafeArea, onClose, onClos
 
 const ToastBase = createOverridable("Toast", DefaultToast);
 
-/**
- * The toast surface. `Toast` (the stack) and `Toast.Item` (one card) each resolve to a route-scoped override
- * when a `page/**\/_overrides.tsx` in the route's ancestry declares one (slots `Toast`, `ToastItem`).
- *
- * `System`'s `Messages` renders this and is not a slot: it keeps the `msg.*` wiring, the store read, the
- * body-level portal and the dismiss timers, so a replacement re-skins the surface without re-implementing
- * when a toast appears and goes away.
- */
+/** `System`'s `Messages` keeps the timers, portal and store wiring, so a replacement only re-skins the surface. */
 export const Toast = Object.assign(ToastBase, {
   Item: createOverridable("ToastItem", DefaultToastItem),
 });

package/ui/ToggleSelect.tsx

@@ -3,9 +3,9 @@ import { cn, usePage } from "akanjs/client";
 import { type ComponentType, createElement, Fragment, type ReactNode } from "react";
 
 import { buttonRecipe } from "./Button";
+import { InvalidMessage, invalidMessageOf } from "./Input";
 import { createOverridable, useUiOverride, useUiRecipe } from "./UiOverride";
 
-/** Toggle-select cell: outline button (recipe slot), filled primary when selected. */
 const selectedCls = "border-transparent bg-primary text-primary-foreground hover:bg-primary/90";
 
 export interface ToggleSelectProps<I extends string | number | boolean | null> {
@@ -39,12 +39,11 @@ const DefaultToggleSelect = <I extends string | number | boolean | null>({
   const { l } = usePage();
   const toggleBtn = (useUiRecipe("button") ?? buttonRecipe)({ variant: "outline", size: "sm" });
   const validateResult = value !== null ? validate(value) : false;
-  const invalidMessage =
-    value === null || (typeof value === "string" && !value.length) || validateResult === true
-      ? null
-      : validateResult === false
-        ? l("base.invalidValueError")
-        : validateResult;
+  const invalidMessage = invalidMessageOf(
+    value === null || (typeof value === "string" && !value.length),
+    validateResult,
+    l,
+  );
   const options = items.map(
     (item) =>
       (typeof item === "string" || typeof item === "number" ? { label: item.toString(), value: item } : item) as {
@@ -80,9 +79,7 @@ const DefaultToggleSelect = <I extends string | number | boolean | null>({
           </button>
         );
       })}
-      {invalidMessage ? (
-        <div className="absolute -bottom-4 animate-fadeIn text-destructive text-xs">{invalidMessage}</div>
-      ) : null}
+      <InvalidMessage message={invalidMessage} />
     </div>
   );
 };
@@ -110,12 +107,7 @@ const DefaultMulti = ({
   const { l } = usePage();
   const toggleBtn = (useUiRecipe("button") ?? buttonRecipe)({ variant: "outline", size: "sm" });
   const validateResult = validate(value);
-  const invalidMessage =
-    !value.length || validateResult === true
-      ? null
-      : validateResult === false
-        ? l("base.invalidValueError")
-        : validateResult;
+  const invalidMessage = invalidMessageOf(!value.length, validateResult, l);
   const options = items.map(
     (item) =>
       (typeof item === "string" || typeof item === "number" ? { label: item.toString(), value: item } : item) as {
@@ -155,23 +147,17 @@ const DefaultMulti = ({
           </button>
         );
       })}
-      {invalidMessage ? (
-        <div className="absolute -bottom-4 animate-fadeIn text-destructive text-xs">{invalidMessage}</div>
-      ) : null}
+      <InvalidMessage message={invalidMessage} />
     </div>
   );
 };
+
 const ToggleSelectBase = <I extends string | number | boolean | null>(props: ToggleSelectProps<I>) => {
   const Override = useUiOverride("ToggleSelect");
   const Impl = (Override ?? DefaultToggleSelect) as unknown as ComponentType<ToggleSelectProps<I>>;
   return createElement(Impl, props);
 };
 
-/**
- * Toggle-select. `ToggleSelect` keeps its generic signature (so `<ToggleSelect<Status> …/>` still
- * infers), and both it and `ToggleSelect.Multi` resolve to a route-scoped override when a
- * `page/**\/_overrides.tsx` in the route's ancestry declares one (slots `ToggleSelect`, `ToggleSelectMulti`).
- */
 export const ToggleSelect = Object.assign(ToggleSelectBase, {
   Multi: createOverridable("ToggleSelectMulti", DefaultMulti),
 });

package/ui/Tooltip.tsx

@@ -5,12 +5,11 @@ import type { ReactNode } from "react";
 import { createOverridable } from "./UiOverride";
 
 export interface TooltipProps {
-  /** 툴팁에 표시할 내용. 비어 있으면 트리거만 그대로 렌더한다. */
+  /** Empty renders the trigger alone. */
   content?: ReactNode;
   children: ReactNode;
   side?: "top" | "right" | "bottom" | "left";
   className?: string;
-  /** 색상 변형. daisyui `tooltip-primary/info` 대체. */
   variant?: "default" | "primary" | "info";
 }
 
@@ -40,15 +39,10 @@ const sideClass = {
   right: "left-full top-1/2 ml-1.5 -translate-y-1/2",
 };
 
-/**
- * 순수 CSS 툴팁 (hover/focus-within). daisyui `tooltip` 및 Radix Tooltip 대체.
- * 트리거를 감싸 hover 또는 키보드 포커스 시 표시한다. 뷰포트 엣지 flip은 없다(힌트 UI 한정).
- * `page/**\/_overrides.tsx`로 라우트별 교체 가능(slot `Tooltip`).
- */
 const DefaultTooltip = ({ content, children, side = "top", className, variant = "default" }: TooltipProps) => {
   if (content === undefined || content === null || content === "") return <>{children}</>;
   return (
-
+    
     <span className="group/tooltip relative inline-flex w-fit">
       {children}
       <span

package/ui/UiOverride/UiOverride.tsx

@@ -0,0 +1,155 @@
+"use client";
+import { type ComponentType, createElement, type ReactNode, useContext, useMemo } from "react";
+import type { ClassNameValue as ClassValue } from "tailwind-merge";
+import { sharedContext } from "../../client/sharedContext";
+import type { ApprovalProps as AgentApprovalProps } from "../Agent/Approval";
+import type { BubbleProps as AgentBubbleProps } from "../Agent/Bubble";
+import type { ChatProps as AgentChatProps } from "../Agent/Chat";
+import type { ComposerProps as AgentComposerProps } from "../Agent/Composer";
+import type { LauncherProps as AgentLauncherProps } from "../Agent/Launcher";
+import type { CodeProps as AgentCodeProps, MarkdownProps as AgentMarkdownProps } from "../Agent/Markdown";
+import type { MenuProps as AgentMenuProps } from "../Agent/Menu";
+import type { QuestionProps as AgentQuestionProps } from "../Agent/Question";
+import type { QueuedProps as AgentQueuedProps } from "../Agent/Queued";
+import type { StepsProps as AgentStepsProps } from "../Agent/Steps";
+import type { ToolCardProps as AgentToolCardProps } from "../Agent/ToolCard";
+import type { BadgeProps } from "../Badge";
+import type { ButtonProps } from "../Button";
+import type { DatePickerProps, RangePickerProps, TimePickerProps } from "../DatePicker";
+import type { DropdownProps } from "../Dropdown";
+import type { EmptyProps } from "../Empty";
+import type { CheckboxProps, EmailProps, InputProps, NumberProps, PasswordProps, TextAreaProps } from "../Input";
+import type { ProgressBarProps } from "../Loading/ProgressBar";
+import type { SkeletonProps } from "../Loading/Skeleton";
+import type { AreaProps, SpinProps } from "../Loading/Spin";
+import type { MenuProps } from "../Menu";
+import type { ModalProps } from "../Modal";
+import type { DraftBarViewProps } from "../Model/DraftBar";
+import type { PaginationProps } from "../Pagination";
+import type { PopconfirmProps } from "../Popconfirm";
+import type { ItemProps as RadioItemProps, RadioProps } from "../Radio";
+import type { BadgeVariants, ButtonVariants, InputSurfaceVariants } from "../recipe";
+import type { SelectProps } from "../Select";
+import type { TableProps } from "../Table";
+import type { ToastItemProps, ToastProps } from "../Toast";
+import type { MultiProps as ToggleSelectMultiProps, ToggleSelectProps } from "../ToggleSelect";
+import type { TooltipProps } from "../Tooltip";
+import type { UnauthorizedProps } from "../Unauthorized";
+
+/** Components a `page/**\/_overrides.tsx` manifest may replace, each typed to its public prop contract. */
+export interface AkanUiOverrides {
+  Badge: ComponentType<BadgeProps>;
+  Modal: ComponentType<ModalProps>;
+  Empty: ComponentType<EmptyProps>;
+  Pagination: ComponentType<PaginationProps>;
+  Popconfirm: ComponentType<PopconfirmProps>;
+  Dropdown: ComponentType<DropdownProps>;
+  Table: ComponentType<TableProps>;
+  Menu: ComponentType<MenuProps>;
+  Tooltip: ComponentType<TooltipProps>;
+  Unauthorized: ComponentType<UnauthorizedProps>;
+  DraftBar: ComponentType<DraftBarViewProps>;
+  AgentChat: ComponentType<AgentChatProps>;
+
+  AgentLauncher: ComponentType<AgentLauncherProps>;
+  AgentBubble: ComponentType<AgentBubbleProps>;
+  AgentSteps: ComponentType<AgentStepsProps>;
+  AgentComposer: ComponentType<AgentComposerProps>;
+  AgentApproval: ComponentType<AgentApprovalProps>;
+  AgentQuestion: ComponentType<AgentQuestionProps>;
+  AgentQueued: ComponentType<AgentQueuedProps>;
+  AgentMenu: ComponentType<AgentMenuProps>;
+  AgentMarkdown: ComponentType<AgentMarkdownProps>;
+  AgentToolCard: ComponentType<AgentToolCardProps>;
+  AgentCode: ComponentType<AgentCodeProps>;
+
+  Button: ComponentType<ButtonProps<unknown>>;
+  Select: ComponentType<SelectProps<string | number | boolean | null | undefined>>;
+
+  Input: ComponentType<InputProps>;
+  InputTextArea: ComponentType<TextAreaProps>;
+  InputPassword: ComponentType<PasswordProps>;
+  InputEmail: ComponentType<EmailProps>;
+  InputNumber: ComponentType<NumberProps>;
+  InputCheckbox: ComponentType<CheckboxProps>;
+
+  Radio: ComponentType<RadioProps>;
+  RadioItem: ComponentType<RadioItemProps>;
+
+  DatePicker: ComponentType<DatePickerProps>;
+  DatePickerRangePicker: ComponentType<RangePickerProps>;
+  DatePickerTimePicker: ComponentType<TimePickerProps>;
+
+  Toast: ComponentType<ToastProps>;
+  ToastItem: ComponentType<ToastItemProps>;
+
+  ToggleSelect: ComponentType<ToggleSelectProps<string | number | boolean | null>>;
+  ToggleSelectMulti: ComponentType<ToggleSelectMultiProps>;
+
+  LoadingSpin: ComponentType<SpinProps>;
+  LoadingSkeleton: ComponentType<SkeletonProps>;
+  LoadingProgressBar: ComponentType<ProgressBarProps>;
+  LoadingButton: ComponentType<SkeletonProps>;
+  LoadingInput: ComponentType<SkeletonProps>;
+  LoadingArea: ComponentType<AreaProps>;
+}
+
+export type AkanUiOverrideName = keyof AkanUiOverrides;
+
+/** Prop contract an app-authored Modal override must satisfy. */
+export type AkanModalComponent = AkanUiOverrides["Modal"];
+
+/** Recipe slots `override({ recipes })` may swap: a client-side, route-scoped restyle that reaches framework client
+ *  components only, never a raw `xRecipe()` call or a server component. */
+export interface AkanUiRecipes {
+  button: (variants?: ButtonVariants, className?: ClassValue) => string;
+  badge: (variants?: BadgeVariants, className?: ClassValue) => string;
+  input: (variants?: InputSurfaceVariants, className?: ClassValue) => string;
+}
+
+/** Shape of an `_overrides.tsx` manifest: component slots plus an optional recipe-slot map. */
+export type AkanUiOverrideManifest = Partial<AkanUiOverrides> & { recipes?: Partial<AkanUiRecipes> };
+
+export const UiOverrideContext = sharedContext<AkanUiOverrideManifest>("uiOverride", {});
+
+/** The active override for `name` in this route subtree, or `undefined`. */
+export const useUiOverride = <K extends keyof AkanUiOverrides>(name: K): AkanUiOverrides[K] | undefined => {
+  
+  const overrides = useContext(UiOverrideContext) as Record<string, unknown>;
+  return overrides[name] as AkanUiOverrides[K] | undefined;
+};
+
+/** The active recipe swap for `name` in this route subtree, or `undefined`. */
+export const useUiRecipe = <K extends keyof AkanUiRecipes>(name: K): AkanUiRecipes[K] | undefined => {
+  const { recipes } = useContext(UiOverrideContext);
+  return recipes?.[name];
+};
+
+/** Renders the nearest `_overrides.tsx` entry for `name`, else `Default`. */
+export const createOverridable = <K extends keyof AkanUiOverrides>(
+  name: K,
+  Default: AkanUiOverrides[K],
+): AkanUiOverrides[K] => {
+  
+  const Fallback = Default as unknown as ComponentType<Record<string, unknown>>;
+  const Overridable = (props: Record<string, unknown>): ReactNode => {
+    const Override = useUiOverride(name) as unknown as ComponentType<Record<string, unknown>> | undefined;
+    return createElement(Override ?? Fallback, props);
+  };
+  return Overridable as unknown as AkanUiOverrides[K];
+};
+
+export interface UiOverrideProviderProps {
+  value?: AkanUiOverrideManifest;
+  children?: ReactNode;
+}
+
+/** Merges `value` over the inherited overrides (closest wins; `recipes` merges per slot). */
+export const UiOverrideProvider = ({ value, children }: UiOverrideProviderProps) => {
+  const parent = useContext(UiOverrideContext);
+  const merged = useMemo(
+    () => ({ ...parent, ...value, recipes: { ...parent.recipes, ...value?.recipes } }),
+    [parent, value],
+  );
+  return <UiOverrideContext.Provider value={merged}>{children}</UiOverrideContext.Provider>;
+};

package/ui/UiOverride/index.ts

@@ -1,12 +1,15 @@
+export { override } from "./override";
 export type {
   AkanModalComponent,
   AkanUiOverrideManifest,
   AkanUiOverrideName,
   AkanUiOverrides,
   AkanUiRecipes,
-} from "./context";
-export { createOverridable } from "./createOverridable";
-export { override } from "./override";
-export { UiOverrideProvider, type UiOverrideProviderProps } from "./Provider";
-export { useUiOverride } from "./useUiOverride";
-export { useUiRecipe } from "./useUiRecipe";
+} from "./UiOverride";
+export {
+  createOverridable,
+  UiOverrideProvider,
+  type UiOverrideProviderProps,
+  useUiOverride,
+  useUiRecipe,
+} from "./UiOverride";

package/ui/UiOverride/override.ts

@@ -1,20 +1,4 @@
-import type { AkanUiOverrideManifest } from "./context";
+import type { AkanUiOverrideManifest } from "./UiOverride";
 
-/**
- * Typed manifest builder for a `page/_overrides.tsx` file:
- *
- * ```tsx
- * export default override({ Modal: BrandModal, recipes: { button: neonButtonRecipe } });
- * ```
- *
- * It type-checks each binding against that slot's public contract and rejects unknown slot names as
- * excess properties — so the manifest is validated at compile time and app components need no annotation of
- * their own. Component keys are the framework component names (`Modal`), matching `useUiOverride` and the
- * `<Modal>` call sites; the optional `recipes` map swaps recipe slots (look only, behavior untouched),
- * matching `useUiRecipe` and the recipe names in `AkanUiRecipes`.
- *
- * It is a pure, server-safe identity function (no React, no `createContext`), so the manifest needs no
- * `"use client"` directive. The framework generates a `"use client"` wrapper layout that reads this map and
- * mounts the override provider around the route subtree (see `writeGeneratedOverridesLayoutFile`).
- */
+/** Checks an `_overrides.tsx` manifest against each slot's contract; a server-safe identity, so no `"use client"`. */
 export const override = (overrides: AkanUiOverrideManifest): AkanUiOverrideManifest => overrides;

package/ui/Unauthorized.tsx

@@ -7,7 +7,6 @@ import { createOverridable } from "./UiOverride";
 
 export interface UnauthorizedProps {
   className?: string;
-  /** The mark above the description. */
   icon?: ReactNode;
   description?: ReactNode;
   children?: ReactNode;
@@ -24,8 +23,7 @@ export const DefaultUnauthorized = ({
   const { l } = usePage();
   return (
     <div>
-      {/* minHeight is a runtime number, so it has to be a style prop — see Empty.tsx. The interpolated form
-          also had `w-full` typo'd inside the brackets, which broke that class too. */}
+      {/* A style, not a class: Tailwind compiles no CSS for an interpolated arbitrary value. */}
       <div
         style={{ minHeight }}
         className={cn("flex w-full flex-col items-center justify-center gap-3 px-6 py-8 text-center", className)}
@@ -40,9 +38,4 @@ export const DefaultUnauthorized = ({
   );
 };
 
-/**
- * Unauthorized-state placeholder. Resolves to a route-scoped override when a
- * `page/**\/_overrides.tsx` in the route's ancestry declares one, otherwise
- * renders {@link DefaultUnauthorized}.
- */
 export const Unauthorized = createOverridable("Unauthorized", DefaultUnauthorized);

package/ui/agentAttrs.ts

@@ -1,19 +1,16 @@
 import { actionTagOf } from "akanjs/store";
 
-/**
- * The `data-akan-*` attributes for a handler the caller passed by reference.
- *
- * `{}` when the handler is an inline arrow, which is the honest answer: a closure the caller wrote says nothing
- * about what it does, and a guessed annotation is worse than none. The house form for a model field is the setter
- * itself (`onChange={st.do.setNameOnUser}`), so the fields that matter are annotated without an app writing anything.
- *
- * What it buys, beyond an in-page agent: an accessibility tree and E2E selectors that name the action rather than a
- * class, and an external browser agent — one this framework has no bridge into — reading the same names.
- */
+/** `data-akan-*` attributes for a handler passed by reference, `{}` for an inline arrow. `key` tells apart the
+ *  controls sharing one handler (a tab's menus, a list's rows), in the vocabulary of the call's argument. */
 export const agentAttrs = (
   handler: unknown,
-): { "data-akan-action"?: string; "data-akan-state"?: string } | Record<string, never> => {
+  key?: string | number,
+): { "data-akan-action"?: string; "data-akan-state"?: string; "data-akan-key"?: string } | Record<string, never> => {
   const tag = actionTagOf(handler);
   if (!tag) return {};
-  return { "data-akan-action": tag.action, ...(tag.state ? { "data-akan-state": tag.state } : {}) };
+  return {
+    "data-akan-action": tag.action,
+    ...(tag.state ? { "data-akan-state": tag.state } : {}),
+    ...(key === undefined || key === "" ? {} : { "data-akan-key": String(key) }),
+  };
 };

package/ui/index.ts

@@ -1,5 +1,5 @@
 
-
+export { type AgentReferenceInput, useAgentReference } from "akanjs/store";
 export {
   AgentProvider,
   type AgentProviderProps,
@@ -10,7 +10,10 @@ export {
   type CompactOptions,
   type ContextBlock,
   httpRunner,
+  type MessageAttachment,
+  type MessageReference,
   type PublishedTool,
+  Reference,
   type RunnerEvent,
   type RunnerRequest,
   SessionContext,
@@ -20,7 +23,14 @@ export {
 } from "../vendor/use-agentic";
 export { Agent } from "./Agent";
 export { type ApprovalProps, DefaultApproval } from "./Agent/Approval";
-export { type AgentSessionSetup, agentSessionOf } from "./Agent/agentSessionOf";
+export { Chips as AgentAttachments, type ChipsProps as AgentAttachmentsProps } from "./Agent/Attach";
+export {
+  type AgentBuiltin,
+  type AgentSessionSetup,
+  agentSessionOf,
+  type BuiltinOption,
+  type PersistOption,
+} from "./Agent/agentSessionOf";
 export {
   type AttachLimits,
   type AttachReader,
@@ -31,7 +41,7 @@ export {
 export { type BubbleProps, DefaultBubble } from "./Agent/Bubble";
 export type { ChatProps } from "./Agent/Chat";
 export { type ChatCommand, ChatCommands } from "./Agent/ChatCommands";
-export { type ComposerProps, DefaultComposer } from "./Agent/Composer";
+export { type ComposerHandle, type ComposerProps, DefaultComposer } from "./Agent/Composer";
 export { fetchRunner } from "./Agent/fetchRunner";
 export type { HistoryProps as AgentHistoryProps } from "./Agent/History";
 export { DefaultLauncher, type LauncherProps } from "./Agent/Launcher";
@@ -39,10 +49,15 @@ export { type CodeProps, DefaultCode, DefaultMarkdown, type MarkdownProps } from
 export { DefaultAgentMenu, type MenuProps as AgentMenuProps, type MenuRow } from "./Agent/Menu";
 export { DefaultQuestion, type QuestionProps } from "./Agent/Question";
 export { DefaultQueued, type QueuedProps } from "./Agent/Queued";
-export type { PersistOption } from "./Agent/sessionHistory";
-export type { AgentBuiltin, BuiltinOption } from "./Agent/sessionView";
+export {
+  ReferenceChips as AgentReferences,
+  type ReferenceChipsProps as AgentReferencesProps,
+} from "./Agent/Refer";
+export { DefaultSteps, type StepsProps } from "./Agent/Steps";
+export { DefaultToolCard, type ToolCardProps } from "./Agent/ToolCard";
 export { tokenCount } from "./Agent/tokenCount";
 export type { QueuedMessage } from "./Agent/useChatQueue";
+export type { ReferenceCandidate, ReferenceSource } from "./Agent/useReferenceMenu";
 export type { VoiceEngine, VoiceHandlers, VoiceListener, VoiceSpeech } from "./Agent/voice";
 export { agentAttrs } from "./agentAttrs";
 export { animated } from "./animated";

package/ui/overlayLayer.ts

@@ -2,46 +2,25 @@
 import { useContext } from "react";
 import { sharedContext } from "../client/sharedContext";
 
-/**
- * Overlay surfaces render through `createPortal(document.body)`, so they leave the DOM subtree of the
- * component that opened them, and a dismiss check asking `ref.current.contains(target)` reads every
- * click inside a dialog it opened *itself* as an outside click.
- *
- * React context reaches through a portal where the DOM does not, so an overlay can read which
- * dismissable scope rendered it and stamp that owner on the roots it portals out. A scope then
- * recognises its own overlays exactly, instead of guessing from how close a dialog happens to be.
- */
 export 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 const overlayZ = { select: 90, dropdown: 100, popconfirmScrim: 105, popconfirm: 110 } as const;
 
-/** Scope that rendered the surrounding content — empty at page level. */
 const OverlayOwnerContext = sharedContext("overlayOwner", "");
 
-/** Wrap the content a dismissable container owns, with the scope from {@link useOverlayScope}. */
+/** Takes the scope from {@link useOverlayScope}. */
 export const OverlayOwnerProvider = OverlayOwnerContext.Provider;
 
-/** Scope a dismissable container hands to its content. Nests as a `parent/child` path. */
+/** Nests under the enclosing scope as a `parent/child` path. */
 export const useOverlayScope = (id: string) => {
   const parent = useContext(OverlayOwnerContext);
   return parent ? `${parent}/${id}` : id;
 };
 
-/** Props an overlay spreads onto every root it portals out of its own tree. */
+/** Spread onto every root an overlay portals out of its own tree. */
 export const useOverlayLayerProps = () => ({ [OVERLAY_LAYER_ATTR]: useContext(OverlayOwnerContext) });
 
-/**
- * True when the click landed in an overlay that `scope` — or a scope nested inside it — rendered.
- * An overlay nobody owns, and one owned by an unrelated scope, both read as an ordinary outside
- * click, so a menu does not linger behind a dialog it has nothing to do with.
- */
+/** True when the click landed in an overlay `scope`, or a scope nested in it, rendered; any other is outside. */
 export const isOwnOverlayClick = (target: EventTarget | null, scope: string) => {
   if (!(target instanceof Element)) return false;
   const owner = target.closest(`[${OVERLAY_LAYER_ATTR}]`)?.getAttribute(OVERLAY_LAYER_ATTR);

package/ui/overlayPosition.ts

@@ -9,23 +9,12 @@ const POINTER_INSET = 16;
 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 const useOverlayPosition = ({
   opened,
   triggerRef,
@@ -37,7 +26,6 @@ export const useOverlayPosition = ({
   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;
 }) => {
   const [position, setPosition] = useState<OverlayPosition | null>(null);
@@ -66,7 +54,7 @@ export const useOverlayPosition = ({
       anchorOffset: clamp((trigger.left + trigger.right) / 2 - left, POINTER_INSET, width - POINTER_INSET),
       anchorWidth: trigger.width,
     };
-
+    
     setPosition((prev) =>
       prev &&
       prev.top === next.top &&
@@ -88,7 +76,7 @@ export const useOverlayPosition = ({
     
     window.addEventListener("scroll", measure, true);
     window.addEventListener("resize", measure);
-
+    
     const panel = panelRef.current;
     const observer = panel ? new ResizeObserver(measure) : null;
     if (panel && observer) observer.observe(panel);

package/ui/recipe/badgeRecipe.ts

@@ -23,7 +23,7 @@ export const badgeRecipe = recipe(
         md: "px-2.5 py-0.5 text-xs",
         lg: "px-3 py-1 text-sm",
       },
-
+      
       outline: { true: "border-current bg-transparent" },
     },
     compoundVariants: [

package/ui/recipe/buttonRecipe.ts

@@ -3,11 +3,11 @@ import { recipe, tv } from "./factory";
 /** 버튼 look — 시맨틱 variant × size × shape, outline 플래그는 색을 유지한 외곽선 스타일. `<Button>` 이 소비하며, `_overrides.tsx` 의 recipes.button 슬롯으로 교체 가능. */
 export const buttonRecipe = recipe(
   tv({
-
+    
     base: "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-field font-medium transition active:scale-95 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
     variants: {
       variant: {
-
+        
         default: "bg-muted text-foreground hover:bg-muted/80",
         primary: "bg-primary text-primary-foreground hover:bg-primary/90",
         secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
@@ -28,13 +28,13 @@ export const buttonRecipe = recipe(
         lg: "h-12 px-6 text-lg",
         icon: "h-10 w-10 px-0",
       },
-
+      
       shape: {
         default: "",
         square: "aspect-square px-0",
         circle: "aspect-square rounded-full px-0",
       },
-
+      
       outline: { true: "border bg-transparent" },
     },
     compoundVariants: [