akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/types/ui/Agent/Chat.d.ts

@@ -0,0 +1,24 @@
+import { type AgentRunner } from "../../vendor/use-agentic.d.ts";
+import { type PersistOption } from "./sessionHistory.d.ts";
+export interface ChatProps {
+    className?: string;
+    title?: string;
+    /** App-global framing. Route-scoped guidance layers on it through mounted `Agent.Guide`s. */
+    instructions?: string;
+    /** Swap the transport; the default drives the app's `runAgentTurn` endpoint. */
+    runner?: AgentRunner;
+    maxTurns?: number;
+    defaultOpen?: boolean;
+    /** Keeps the transcript across reloads — sessionStorage by default, `{ storage: "local" }` to outlive the tab. */
+    persist?: PersistOption;
+}
+/**
+ * The user-facing half of the in-page agent: one floating chat wired to the same surface the dock inspects.
+ * The conversation loop runs in this browser session — every tool call executes here, gated by the approval
+ * card — and the session lives in a ref, so it survives reopening the panel and dies with the page (v1 keeps
+ * no history). An enclosing AgentProvider's session wins, which is how an app isolates a surface or swaps the
+ * loop while keeping this UI.
+ */
+export declare const DefaultChat: ({ className, title, instructions, runner, maxTurns, defaultOpen, persist, }: ChatProps) => import("react/jsx-runtime").JSX.Element;
+declare const _default: import("react").ComponentType<ChatProps>;
+export default _default;

package/types/ui/Agent/Context.d.ts

@@ -0,0 +1,9 @@
+interface ContextProps {
+    className?: string;
+}
+/**
+ * Assembles and shows the exact context blocks a turn would carry, on demand — the one preview of "what does the
+ * agent see on this screen" that no amount of reading the source answers.
+ */
+export default function Context({ className }: ContextProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/types/ui/Agent/Dock.d.ts

@@ -0,0 +1,16 @@
+import { type AgentBridge } from "akanjs/store";
+export interface DockProps {
+    className?: string;
+    /** Pass the bridge an agent is already driving so both write into one transcript. Defaults to the app's own. */
+    bridge?: AgentBridge;
+    open?: boolean;
+}
+/**
+ * The in-page surface of the agent bridge: what this page lets an agent do, what it refused, and what it has done.
+ *
+ * It drives the store directly rather than talking to a model, because a model is not the framework's to choose —
+ * there is no provider or key here. An app wires its own agent to `bridge.tools` / `bridge.call` and can render this
+ * beside it; on its own it is the way to see the catalogue a page actually publishes, which is the one thing no
+ * amount of reading the source answers.
+ */
+export declare const Dock: ({ className, bridge, open }: DockProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/Agent/Guide.d.ts

@@ -0,0 +1,9 @@
+export interface GuideProps {
+    instructions: string;
+}
+/**
+ * Standing agent guidance scoped to a route subtree: render it from a `_layout.tsx` or a page and the text joins
+ * the turn's instructions while that subtree is mounted. Nesting layers naturally — each mounted Guide contributes
+ * its block, and navigating away withdraws it. Renders nothing.
+ */
+export declare const Guide: ({ instructions }: GuideProps) => null;

package/types/ui/Agent/Section.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+interface SectionProps {
+    className?: string;
+    title: string;
+    count: number;
+    children: ReactNode;
+    open?: boolean;
+}
+export default function Section({ className, title, count, children, open }: SectionProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/types/ui/Agent/StateKey.d.ts

@@ -0,0 +1,16 @@
+import type { AgentBridge, SerializedStoreState } from "akanjs/store";
+interface StateKeyProps {
+    className?: string;
+    bridge: AgentBridge;
+    name: string;
+    entry: SerializedStoreState;
+    live?: boolean;
+}
+/**
+ * One readable state key, read on demand rather than rendered with the rest.
+ *
+ * Reading is where masking happens, so a key that holds an object no model claims refuses here instead of in the
+ * catalogue — whether it is readable depends on what is in it, which the catalogue cannot know ahead of time.
+ */
+export default function StateKey({ className, bridge, name, entry, live }: StateKeyProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/types/ui/Agent/Tool.d.ts

@@ -0,0 +1,15 @@
+import type { AgentBridge, AgentTool } from "akanjs/store";
+interface ToolProps {
+    className?: string;
+    bridge: AgentBridge;
+    tool: AgentTool;
+    onRun: () => void;
+}
+/**
+ * One published action, with the arguments as JSON rather than as a generated form.
+ *
+ * A form per argument is what the API explorer does, and it is the wrong trade here: the point of the dock is to
+ * watch a call land in the running app, and every schema shape the store publishes is already legible as JSON.
+ */
+export default function Tool({ className, bridge, tool, onRun }: ToolProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/types/ui/Agent/Transcript.d.ts

@@ -0,0 +1,13 @@
+import type { AgentCall } from "akanjs/store";
+interface TranscriptProps {
+    className?: string;
+    calls: readonly AgentCall[];
+}
+/**
+ * What the agent did, newest last, so the user can check it against what they saw the page do.
+ *
+ * There is no undo here. Every model removal in this framework is soft, so one is possible in principle, but which
+ * writes are reversible is a per-module judgement and `local/agent-native/PLAN.md` §9-3 leaves it open.
+ */
+export default function Transcript({ className, calls }: TranscriptProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/types/ui/Agent/Zone.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+import { type AgentRunner } from "../../vendor/use-agentic.d.ts";
+import { type PersistOption } from "./sessionHistory.d.ts";
+export interface ZoneProps {
+    className?: string;
+    /** Names the zone; the scope id and the `data-agent-zone` container both derive from it. */
+    id: string;
+    label?: string;
+    /** Zone-scoped guidance — a mounted Guide, so the root agent reads it too (ancestor rule), a sibling zone never does. */
+    instructions?: string;
+    runner?: AgentRunner;
+    maxTurns?: number;
+    /** Keeps this zone's transcript across reloads, keyed by the zone's scope path. */
+    persist?: PersistOption;
+    children: ReactNode;
+}
+/**
+ * A zone agent: one subtree with its own conversation over a scoped view of the same surface. Everything mounted
+ * inside — hook tools, `st.use` subscriptions, guides — belongs to this zone's session *and* to the root agent:
+ * zones are views, never walls. An `Agent.Chat` mounted inside binds to this session automatically, so two zones
+ * on one screen run two conversations in parallel, each seeing only its own subtree.
+ */
+export declare const Zone: ({ className, id, label, instructions, runner, maxTurns, persist, children }: ZoneProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/Agent/fetchRunner.d.ts

@@ -0,0 +1,12 @@
+import { type AgentRunner } from "../../vendor/use-agentic.d.ts";
+/**
+ * Runs each assistant turn against the app's own `runAgentTurn` route — service signals mount unprefixed, so the
+ * URL is `<serverHttpUri>/runAgentTurn` — through the shared `httpRunner`, which negotiates streaming via
+ * `accept`: a server that streams answers SSE and the text arrives as it is generated; one that does not answers
+ * the same JSON turn. The client runtime's fetch proxy is only probed for whether the endpoint exists (the util
+ * lib ships one) and for the signed-in JWT; cookies ride the same-origin request on their own. The endpoint is a
+ * stateless relay; the loop and every tool execution stay in this browser session.
+ */
+export declare const fetchRunner: (options?: {
+    fetcher?: typeof globalThis.fetch;
+}) => AgentRunner;

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

@@ -0,0 +1,17 @@
+import Context from "./Context.d.ts";
+import Section from "./Section.d.ts";
+import StateKey from "./StateKey.d.ts";
+import Tool from "./Tool.d.ts";
+import Transcript from "./Transcript.d.ts";
+export declare const Agent: {
+    Chat: import("react").ComponentType<import("./Chat.d.ts").ChatProps>;
+    Context: typeof Context;
+    Dock: ({ className, bridge, open }: import("./Dock.d.ts").DockProps) => import("react/jsx-runtime").JSX.Element;
+    Guide: ({ instructions }: import("./Guide.d.ts").GuideProps) => null;
+    Scope: ({ id, label, kind, children }: import("../../vendor/use-agentic.d.ts").AgentScopeProps) => import("react/jsx-runtime").JSX.Element;
+    Section: typeof Section;
+    StateKey: typeof StateKey;
+    Tool: typeof Tool;
+    Transcript: typeof Transcript;
+    Zone: ({ className, id, label, instructions, runner, maxTurns, persist, children }: import("./Zone.d.ts").ZoneProps) => import("react/jsx-runtime").JSX.Element;
+};

package/types/ui/Agent/index_.d.ts

@@ -0,0 +1 @@
+export declare const Chat: import("react").ComponentType<import("./Chat.d.ts").ChatProps>;

package/types/ui/Agent/sessionHistory.d.ts

@@ -0,0 +1,12 @@
+import type { SessionHistory } from "../../vendor/use-agentic.d.ts";
+export type PersistOption = boolean | {
+    storage?: "session" | "local";
+    key?: string;
+};
+/**
+ * Maps the `persist` prop onto a `SessionHistory` over web storage. Session storage is the default on purpose:
+ * surviving a refresh is the whole ask, and a transcript that dies with the tab never lingers on a shared machine
+ * or collides across tabs. `"local"` is the explicit opt-up. The envelope is versioned so a wire change discards
+ * stale transcripts instead of replaying them, and only the newest messages are kept under the cap.
+ */
+export declare const sessionHistoryOf: (persist: PersistOption | undefined, pathKey?: string) => SessionHistory | undefined;

package/types/ui/Agent.d.ts

@@ -0,0 +1 @@
+export * from "./Agent/index.d.ts";

package/types/ui/Badge.d.ts

@@ -1,6 +1,6 @@
 import type { HTMLAttributes } from "react";
 import { type BadgeVariants, badgeRecipe } from "./recipe.d.ts";
-export { badgeRecipe, type BadgeVariants };
+export { type BadgeVariants, badgeRecipe };
 export type BadgeProps = HTMLAttributes<HTMLSpanElement> & BadgeVariants;
 /** Status/label pill. Route-overridable via `page/**\/_overrides.tsx` (slot `Badge`). */
 export declare const Badge: import("react").ComponentType<BadgeProps>;

package/types/ui/Button.d.ts

@@ -1,7 +1,7 @@
 import type React from "react";
 import { type ButtonHTMLAttributes } from "react";
 import { type ButtonVariants, buttonRecipe } from "./recipe.d.ts";
-export { buttonRecipe, type ButtonVariants };
+export { type ButtonVariants, buttonRecipe };
 export type ButtonProps<Result> = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> & ButtonVariants & {
     /**
      * Click handler. Returning a promise is what opts this button into the async states — a plain

package/types/ui/CsrImage.d.ts

@@ -7,7 +7,7 @@ type CsrImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, "alt" | "src"> &
         imageSize: [number, number];
         abstractData?: string | null;
     } | null;
-    abstractData?: string;
+    abstractData?: string | null;
     priority?: boolean;
     preload?: boolean;
     quality?: number;

package/types/ui/Dropdown.d.ts

@@ -1,4 +1,6 @@
 import { type ReactNode } from "react";
+/** Put this on a menu item that runs its own interaction (a switch, a copy button) to keep the menu open. */
+export declare const DROPDOWN_KEEP_OPEN_ATTR = "data-dropdown-keep-open";
 export interface DropdownProps {
     /** Button/trigger content. */
     value: ReactNode;

package/types/ui/Image.d.ts

@@ -19,7 +19,7 @@ type AkanImageProps = NativeImageProps & {
     /** Akan file object or file-like value with url and imageSize metadata. */
     file?: ImageLikeFile;
     /** Low-quality preview data. Overrides file.abstractData when provided. */
-    abstractData?: string;
+    abstractData?: string | null;
     /** Accessible alt text. Defaults to "image" when omitted. */
     alt?: string;
     /** Image optimizer quality. Defaults to 75. */
@@ -34,11 +34,11 @@ type AkanImageProps = NativeImageProps & {
 export declare const Image: ({ src, file, className, abstractData, alt, quality, priority, preload, unoptimized, ...props }: AkanImageProps & ({
     src?: string;
     file?: ProtoFile;
-    abstractData?: string;
+    abstractData?: string | null;
     alt?: string;
 } | {
     src?: undefined;
-    abstractData?: string;
+    abstractData?: string | null;
     file: {
         url: string;
         imageSize: [number, number];

package/types/ui/Layout/BottomInset.d.ts

@@ -4,10 +4,11 @@ export interface BottomInsetProps {
     className?: string;
     children: ReactNode;
     keyboardSticky?: boolean;
+    contentAnchor?: "bottom";
     role?: "bottomChrome" | "keyboardAccessory";
     estimatedHeight?: number;
     frameScope?: FrameSlotRegistration["scope"];
     frameSource?: FrameSlotRegistration["source"];
     frameCache?: boolean;
 }
-export declare const BottomInset: ({ className, children, keyboardSticky, role, estimatedHeight, frameScope, frameSource, frameCache, }: BottomInsetProps) => import("react/jsx-runtime").JSX.Element;
+export declare const BottomInset: ({ className, children, keyboardSticky, contentAnchor, role, estimatedHeight, frameScope, frameSource, frameCache, }: BottomInsetProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -4,7 +4,7 @@ export declare const Layout: {
     Navbar: ({ back, className, height, children, title, left, right }: import("./Navbar.d.ts").NavbarProps) => import("react/jsx-runtime").JSX.Element;
     TopInset: ({ className, children, estimatedHeight }: import("./TopInset.d.ts").TopInsetProps) => import("react/jsx-runtime").JSX.Element;
     BottomTab: ({ className, tabs, height }: import("./BottomTab.d.ts").BottomTabProps) => import("react/jsx-runtime").JSX.Element;
-    BottomInset: ({ className, children, keyboardSticky, role, estimatedHeight, frameScope, frameSource, frameCache, }: import("./BottomInset.d.ts").BottomInsetProps) => import("react/jsx-runtime").JSX.Element;
+    BottomInset: ({ className, children, keyboardSticky, contentAnchor, role, estimatedHeight, frameScope, frameSource, frameCache, }: import("./BottomInset.d.ts").BottomInsetProps) => import("react/jsx-runtime").JSX.Element;
     Template: ({ className, children }: import("./Template.d.ts").TemplateProps) => import("react/jsx-runtime").JSX.Element;
     Unit: ({ className, children, href }: import("./Unit.d.ts").UnitProps) => import("react/jsx-runtime").JSX.Element;
     View: ({ className, children }: import("./View.d.ts").ViewProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/Signal/style.d.ts

@@ -8,7 +8,10 @@ export declare const signalUi: {
     inputLabel: string;
     codePanel: string;
 };
+/** Writes carry the accent, reads do not — so the two write types are named and everything else reads. */
 export declare const getEndpointBadgeClassName: (type: string) => string;
 export declare const getGuardBadgeClassName: (guard: string) => string;
+/** Published to agents carries the accent; opted in and refused is outlined, because it is a thing to go fix. */
+export declare const getMcpBadgeClassName: (exposed: boolean) => string;
 export declare const getStatusBadgeClassName: (status: string) => string;
-export declare const getStatusTextareaClassName: (status: string) => "" | "pointer-events-none opacity-50" | "border-destructive text-destructive" | "border-primary";
+export declare const getStatusTextareaClassName: (status: string) => "" | "border-primary" | "pointer-events-none opacity-50" | "border-destructive text-destructive";

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

@@ -1,5 +1,6 @@
 import { type ComponentType } from "react";
 import type { ClassNameValue as ClassValue } from "tailwind-merge";
+import type { ChatProps as AgentChatProps } from "../Agent/Chat.d.ts";
 import type { BadgeProps } from "../Badge.d.ts";
 import type { ButtonProps } from "../Button.d.ts";
 import type { DatePickerProps, RangePickerProps, TimePickerProps } from "../DatePicker.d.ts";
@@ -16,7 +17,7 @@ import type { ModalProps } from "../Modal.d.ts";
 import type { PaginationProps } from "../Pagination.d.ts";
 import type { PopconfirmProps } from "../Popconfirm.d.ts";
 import type { ItemProps as RadioItemProps, RadioProps } from "../Radio.d.ts";
-import type { BadgeVariants, ButtonVariants } from "../recipe.d.ts";
+import type { BadgeVariants, ButtonVariants, InputSurfaceVariants } from "../recipe.d.ts";
 import type { SelectProps } from "../Select.d.ts";
 import type { TableProps } from "../Table.d.ts";
 import type { MultiProps as ToggleSelectMultiProps, ToggleSelectProps } from "../ToggleSelect.d.ts";
@@ -45,6 +46,7 @@ export interface AkanUiOverrides {
     Menu: ComponentType<MenuProps>;
     Tooltip: ComponentType<TooltipProps>;
     Unauthorized: ComponentType<UnauthorizedProps>;
+    AgentChat: ComponentType<AgentChatProps>;
     Button: ComponentType<ButtonProps<unknown>>;
     Select: ComponentType<SelectProps<string | number | boolean | null | undefined>>;
     Input: ComponentType<InputProps>;
@@ -75,11 +77,21 @@ export type AkanModalComponent = AkanUiOverrides["Modal"];
  * manifest: `override({ recipes: { button: neonButtonRecipe } })`. A recipe swap changes
  * only the className factory — the component's structure/behavior (async states, focus,
  * a11y) is untouched. Each replacement must accept the framework recipe's full variant
- * contract, so every call site keeps working.
+ * contract, so every call site keeps working (a replacement with *extra* optional axes is
+ * assignable — contravariance — but those axes are only reachable from code that knows the
+ * replacement's own type).
+ *
+ * Scope: a recipe slot is a **client-side, route-scoped restyle**. It reaches framework
+ * client components, which resolve through `useUiRecipe(...)`. It never reaches a raw
+ * `xRecipe(...)` call in app JSX (statically imported — no context), nor server components
+ * (`Unit`/`View`), which intentionally render the canonical framework recipe. Extending the
+ * *vocabulary* is not this slot's job: add the axis to the framework recipe, or author an
+ * app recipe in `apps/<app>/ui/Recipe/`.
  */
 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> & {

package/types/ui/agentAttrs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+export declare const agentAttrs: (handler: unknown) => {
+    "data-akan-action"?: string;
+    "data-akan-state"?: string;
+} | Record<string, never>;

package/types/ui/index.d.ts

@@ -1,3 +1,5 @@
+export { Agent } from "./Agent.d.ts";
+export { agentAttrs } from "./agentAttrs.d.ts";
 export { animated } from "./animated.d.ts";
 export { Badge } from "./Badge.d.ts";
 export { BottomSheet, type BottomSheetRef } from "./BottomSheet.d.ts";
@@ -12,7 +14,7 @@ export { DatePicker } from "./DatePicker.d.ts";
 export { Dialog } from "./Dialog.d.ts";
 export { DragAction } from "./DragAction.d.ts";
 export { DraggableList } from "./DraggableList.d.ts";
-export { Dropdown } from "./Dropdown.d.ts";
+export { DROPDOWN_KEEP_OPEN_ATTR, Dropdown } from "./Dropdown.d.ts";
 export { Empty } from "./Empty.d.ts";
 export { Field } from "./Field.d.ts";
 export { FontFace } from "./FontFace.d.ts";
@@ -29,6 +31,7 @@ export { Modal } from "./Modal.d.ts";
 export { Model } from "./Model.d.ts";
 export { More } from "./More.d.ts";
 export { ObjectId } from "./ObjectId.d.ts";
+export { isOwnOverlayClick, OVERLAY_LAYER_ATTR, OverlayOwnerProvider, useOverlayLayerProps, useOverlayScope, } from "./overlayLayer.d.ts";
 export { Pagination } from "./Pagination.d.ts";
 export { Popconfirm } from "./Popconfirm.d.ts";
 export { Portal } from "./Portal.d.ts";

package/types/ui/overlayLayer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 declare const OVERLAY_LAYER_ATTR = "data-akan-overlay";
+/** 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. */
+export declare const useOverlayScope: (id: string) => string;
+/** Props an overlay spreads onto every root it portals out of its own tree. */
+export declare const useOverlayLayerProps: () => {
+    "data-akan-overlay": string;
+};
+/**
+ * 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.
+ */
+export declare const isOwnOverlayClick: (target: EventTarget | null, scope: string) => boolean;

package/types/ui/recipe/badgeRecipe.d.ts

@@ -1,11 +1,15 @@
-/** 뱃지 look — 시맨틱 variant. `<Badge>` 가 소비하며, recipes.badge 슬롯으로 교체 가능. */
+/** 뱃지 look — 시맨틱 variant × size, outline 플래그는 색을 유지한 외곽선 스타일. `<Badge>` 가 소비하며, recipes.badge 슬롯으로 교체 가능. */
 export declare const badgeRecipe: (variants?: Omit<({
-    variant?: "default" | "error" | "info" | "warning" | "success" | "primary" | "secondary" | "accent" | "outline" | undefined;
+    size?: "lg" | "md" | "sm" | "xs" | undefined;
+    outline?: boolean | undefined;
+    variant?: "default" | "error" | "info" | "success" | "warning" | "primary" | "secondary" | "accent" | "neutral" | "outline" | undefined;
 } & {
     class?: import("tailwind-variants").ClassValue;
     className?: never;
 }) | ({
-    variant?: "default" | "error" | "info" | "warning" | "success" | "primary" | "secondary" | "accent" | "outline" | undefined;
+    size?: "lg" | "md" | "sm" | "xs" | undefined;
+    outline?: boolean | undefined;
+    variant?: "default" | "error" | "info" | "success" | "warning" | "primary" | "secondary" | "accent" | "neutral" | "outline" | undefined;
 } & {
     class?: never;
     className?: import("tailwind-variants").ClassValue;

package/types/ui/recipe/buttonRecipe.d.ts

@@ -1,13 +1,17 @@
-/** 버튼 look — 시맨틱 variant × size. `<Button>` 이 소비하며, `_overrides.tsx` 의 recipes.button 슬롯으로 교체 가능. */
+/** 버튼 look — 시맨틱 variant × size × shape, outline 플래그는 색을 유지한 외곽선 스타일. `<Button>` 이 소비하며, `_overrides.tsx` 의 recipes.button 슬롯으로 교체 가능. */
 export declare const buttonRecipe: (variants?: Omit<({
     size?: "lg" | "md" | "sm" | "xs" | "icon" | undefined;
-    variant?: "link" | "info" | "warning" | "success" | "primary" | "secondary" | "accent" | "destructive" | "outline" | "ghost" | undefined;
+    outline?: boolean | undefined;
+    variant?: "link" | "default" | "info" | "success" | "warning" | "primary" | "secondary" | "accent" | "destructive" | "neutral" | "outline" | "ghost" | undefined;
+    shape?: "default" | "circle" | "square" | undefined;
 } & {
     class?: import("tailwind-variants").ClassValue;
     className?: never;
 }) | ({
     size?: "lg" | "md" | "sm" | "xs" | "icon" | undefined;
-    variant?: "link" | "info" | "warning" | "success" | "primary" | "secondary" | "accent" | "destructive" | "outline" | "ghost" | undefined;
+    outline?: boolean | undefined;
+    variant?: "link" | "default" | "info" | "success" | "warning" | "primary" | "secondary" | "accent" | "destructive" | "neutral" | "outline" | "ghost" | undefined;
+    shape?: "default" | "circle" | "square" | undefined;
 } & {
     class?: never;
     className?: import("tailwind-variants").ClassValue;

package/types/ui/recipe/inputRecipe.d.ts

@@ -1,11 +1,15 @@
-/** 입력 표면 look — Input/TextArea 가 공유하는 필드 셸. kind 로 한 줄 필드(field)/멀티라인(area)을 고른다. */
+/** 입력 표면 look — Input/TextArea/Select 가 공유하는 필드 셸. kind 로 한 줄 필드(field)/멀티라인(area), tone 으로 강조/오류 상태를 고른다. */
 export declare const inputRecipe: (variants?: Omit<({
+    size?: "xl" | "lg" | "md" | "sm" | "xs" | undefined;
     kind?: "field" | "area" | undefined;
+    tone?: "default" | "error" | "primary" | undefined;
 } & {
     class?: import("tailwind-variants").ClassValue;
     className?: never;
 }) | ({
+    size?: "xl" | "lg" | "md" | "sm" | "xs" | undefined;
     kind?: "field" | "area" | undefined;
+    tone?: "default" | "error" | "primary" | undefined;
 } & {
     class?: never;
     className?: import("tailwind-variants").ClassValue;

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

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+import { AgenticSurface } from "./AgenticSurface.d.ts";
+import { AgentSession, type AgentSessionOptions } from "./AgentSession.d.ts";
+import type { AgentRunner } from "./types.d.ts";
+interface AgentProviderProps extends AgentSessionOptions {
+    surface?: AgenticSurface;
+    session?: AgentSession;
+    runner?: AgentRunner;
+    children: ReactNode;
+}
+/**
+ * Scopes a subtree onto one surface and, when a runner or session is given, one conversation.
+ *
+ * Without a provider, hooks land on `AgenticSurface.shared` — a provider exists to isolate, or to hold the session
+ * `useAgent` reads.
+ */
+export declare const AgentProvider: ({ surface, session, runner, children, ...options }: AgentProviderProps) => import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+export interface AgentScopeProps {
+    id: string;
+    label?: string;
+    kind?: string;
+    children: ReactNode;
+}
+/** Namespaces every tool and resource registered below it, so list items can reuse local names. */
+export declare const AgentScope: ({ id, label, kind, children }: AgentScopeProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,50 @@
+import type { AgentRunner, ChatMessage, ContextBlock, SurfaceView } from "./types.d.ts";
+export interface PendingApproval {
+    callId: string;
+    name: string;
+    args: Record<string, unknown>;
+    message: string;
+    approve: () => void;
+    reject: (reason?: string) => void;
+}
+/** Where a session keeps its transcript across page loads. Storage-neutral: the host decides what backs it. */
+export interface SessionHistory {
+    load(): ChatMessage[] | null;
+    save(messages: readonly ChatMessage[]): void;
+    clear(): void;
+}
+export interface AgentSessionOptions {
+    instructions?: string;
+    buildContext?: (surface: SurfaceView) => ContextBlock[];
+    /** Assistant turns per send before the session stops the loop. */
+    maxTurns?: number;
+    /** Restores settled messages at construction and saves after every change, debounced. Failures are silent. */
+    history?: SessionHistory;
+}
+/**
+ * The client-side conversation loop: send → model turn → tool calls → approval gate → execute → report diffs → next
+ * turn. The loop lives here rather than on a server because the tools do — the runner is one stateless model turn,
+ * so any backend that answers it works and none has to hold a session.
+ *
+ * Failures land in the transcript instead of being thrown past it: a refused guard, a rejected approval, and an
+ * unknown tool are all things the agent did, and the model reads them as tool results the same way a person reads
+ * them in the chat.
+ */
+export declare class AgentSession {
+    #private;
+    constructor(surface: SurfaceView, runner: AgentRunner, options?: AgentSessionOptions);
+    get surface(): SurfaceView;
+    get messages(): readonly ChatMessage[];
+    get isRunning(): boolean;
+    get pendingApproval(): PendingApproval | null;
+    /** Bumped on every change, so a store binding can use it as the snapshot. */
+    get version(): number;
+    subscribe: (listener: () => void) => () => void;
+    /** A user's text, or prewritten messages — how a host injects a prompt's result as the user's turn. */
+    send: (input: string | ChatMessage[]) => Promise<void>;
+    abort: () => void;
+    /** Empties the transcript and the persisted history. A running turn keeps its transcript. */
+    reset: () => void;
+    /** Records a host-side failure (a prompt fetch, an upload) in the transcript, where every other failure lands. */
+    report: (error: string) => void;
+}

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

@@ -0,0 +1,21 @@
+import { type ReactElement } from "react";
+import type { ToolConfirm, ToolEffect } from "./types.d.ts";
+interface AgenticProps {
+    name: string;
+    description?: string;
+    effect?: ToolEffect;
+    confirm?: ToolConfirm;
+    children: ReactElement<{
+        onClick?: () => unknown;
+    }>;
+}
+/**
+ * Registers the child's `onClick` as a no-argument tool and renders the child untouched.
+ *
+ * The first-class path is passing a hook-made tool by reference as the handler itself; this wrapper is for
+ * elements whose handler you do not own — third-party components and embeds.
+ */
+export declare const Agentic: ({ name, description, effect, confirm, children }: AgenticProps) => ReactElement<{
+    onClick?: () => unknown;
+}, string | import("react").JSXElementConstructor<any>>;
+export {};

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

@@ -0,0 +1,44 @@
+import type { ResourceDiff, ResourceEntry, ScopeEntry, SurfaceSnapshot, SurfaceSource, SurfaceView, ToolEntry } from "./types.d.ts";
+/**
+ * The live registry of what the mounted screen offers an agent: tools, readable resources, and scopes.
+ *
+ * Entries come and go with component lifetimes, so unlike a static catalogue this is subscribable and every
+ * snapshot answers "now". A registration stack backs each name — remounts are ordinary React behavior, so a
+ * duplicate name warns and the newest wins instead of throwing, and unregistering restores what it shadowed.
+ */
+export declare class AgenticSurface {
+    #private;
+    /** One surface per runtime unless a provider isolates its own. Keyed on `globalThis` so duplicated module copies still meet. */
+    static get shared(): AgenticSurface;
+    /** MCP tool names allow `[A-Za-z0-9_.-]`, and `.` is the scope join — so every part is folded into `[A-Za-z0-9_-]`. */
+    static sanitize(part: string): string;
+    static childPath(parent: string[], id: string): string[];
+    static fullName(scope: string[], name: string): string;
+    subscribe(listener: () => void): () => void;
+    registerTool(scope: string[], entry: ToolEntry): () => void;
+    registerResource(scope: string[], entry: ResourceEntry): () => void;
+    openScope(parent: string[], scope: ScopeEntry): () => void;
+    /**
+     * Standing guidance for the agent while the registrant is mounted — instructions, not context data. Kept in
+     * registration order rather than sorted: guides are prose, and each one must stay a coherent block.
+     */
+    registerGuide(scope: string[], text: string): () => void;
+    addSource(source: SurfaceSource): () => void;
+    snapshot(view?: string[]): SurfaceSnapshot;
+    /**
+     * A zone session's reading half: the same registry filtered to one scope subtree. Hook entries filter by their
+     * scope-prefixed name, sources decide for themselves per view, and guides follow the layout cascade — a zone
+     * reads its ancestors' guidance plus its own, never a sibling's. The empty path is the surface itself.
+     */
+    view(path: string[]): SurfaceView;
+    tool(name: string, view?: string[]): ToolEntry | null;
+    call(name: string, args?: Record<string, unknown>, view?: string[]): Promise<unknown>;
+    read(name: string, view?: string[]): unknown;
+    /**
+     * The resources that changed since `before`, for reporting a tool call's effect back to the model.
+     *
+     * Runs against the live entries rather than a second snapshot because `report: false` lives on the entry, and a
+     * snapshot deliberately does not publish it.
+     */
+    diffSince(before: SurfaceSnapshot, view?: string[]): ResourceDiff[];
+}