@guuey/agent-layout 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loqu, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @guuey/agent-layout
+
+**Agent-mode layout** — the layout category for surfaces where an app and its
+agent share one screen: app menus in the upper sidebar, the agent rail below,
+and a content pane whose ground **follows the user's attention** between the
+two. Address the agent and the pane takes the agent's tone; navigate and it
+returns to the app's. One law: _layout follows attention; transport owns the
+stream_ — the tone flips on submit, never on stream events, and interrupting
+is the transport's business.
+
+```tsx
+import {
+  AgentModeProvider,
+  AgentModeShell,
+  AgentModeSidebar,
+  SidebarPanel,
+  ActivePane,
+  bindGuueyChat,
+  useAgentMode,
+} from "@guuey/agent-layout/react";
+import "@guuey/agent-layout/styles.css";
+
+function Shell() {
+  const { dispatch } = useAgentMode();
+  return (
+    <AgentModeShell>
+      <AgentModeSidebar>
+        <SidebarPanel section="app">{/* your menus — zero wiring */}</SidebarPanel>
+        <SidebarPanel section="agent">
+          <GuueyChat {...bindGuueyChat(dispatch)} />
+        </SidebarPanel>
+      </AgentModeSidebar>
+      <ActivePane>{/* your routes / canvas */}</ActivePane>
+    </AgentModeShell>
+  );
+}
+
+<AgentModeProvider mode={mode} navigationKey={pathname} identity={<Logo />}>
+  <Shell />
+</AgentModeProvider>;
+```
+
+- **Two tones, calibrated**: the default pair is the founder-certified
+  warm-paper/neutral-chrome step, light and dark. Overrides are validated
+  against a perceptibility floor (ΔL\* ≥ 6, or a hue-temperature step) —
+  two tones that measure alike are rejected with an explanation.
+- **Route-derived follow**: pass your router's location key as
+  `navigationKey`; every navigation returns the pane to the app tone with
+  zero per-link wiring. Same-page menu clicks are caught by the app panel's
+  capture-phase listener.
+- **No stale-content hold**: while the agent has the room and nothing is
+  presented yet, the pane shows a working state (your `identity` + pulse),
+  never the previous page under the agent's tone.
+- **Mode-aware**: pass the same `mode` you give your chat surface — the lib
+  rides your existing light/dark machinery and adds none of its own.
+- **Not a chat dependency**: `bindGuueyChat` pairs with `@guuey/chat`
+  structurally; any agent surface can call the machine directly through
+  `useAgentMode()`.
+
+React DOM only, zero runtime dependencies, `react >= 18` peer.

package/dist/bind.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The `@guuey/chat` bridge (guuey#403 §4) — pairs with the kit WITHOUT
+ * importing it. This package deliberately has NO dependency on
+ * `@guuey/chat` (the layout stays consumable by a surface that brings its
+ * own agent — ggui console's path calls `agentSubmit()` from
+ * `useAgentMode()` directly), so the kit's shapes are mirrored here
+ * STRUCTURALLY, the fs-contract discipline:
+ *
+ *  - {@link GuueyChatActivityEventShape} mirrors `GuueyChatActivityEvent`
+ *    (oss/packages/chat/src/react/guuey-chat.tsx — sync comment on the
+ *    definition points back here);
+ *  - {@link PlanViewSummaryShape} mirrors the two fields of
+ *    `PlanViewSummary` this bridge reads (`key`, `origin`).
+ *
+ * The template's typecheck is the seam prover: it passes GuueyChat's real
+ * callbacks into these structural slots — a drift on either side breaks
+ * the template build, never silently.
+ */
+import type { AgentModeInput } from "./machine.js";
+/**
+ * Structural mirror of `GuueyChatActivityEvent` (@guuey/chat). `submit`
+ * fires on every successful send — composer, `handle.send`, and the
+ * `ui/message` doorbell paths alike; `settled` fires when the invoke
+ * returns to `ready` (success, error, and abort all settle).
+ */
+export interface GuueyChatActivityEventShape {
+    type: "submit" | "settled";
+}
+/** The two roster fields the bridge reads (structural `PlanViewSummary`). */
+export interface PlanViewSummaryShape {
+    key: string;
+    origin: "live" | "history";
+}
+/** What the bridge needs from the layout side — `useAgentMode().dispatch`. */
+export type AgentModeBinding = (input: AgentModeInput) => void;
+/** The GuueyChat-shaped props {@link bindGuueyChat} returns. */
+export interface GuueyChatBindingProps {
+    onActivity: (event: GuueyChatActivityEventShape) => void;
+    onViewsChange: (views: readonly PlanViewSummaryShape[]) => void;
+}
+/**
+ * Wire a GuueyChat surface into the active-panel machine: spread the
+ * returned props onto `<GuueyChat>` (or compose them inside your own
+ * handlers — each is a plain function).
+ *
+ *  - `submit` → `agentSubmit` (tone flips ON SUBMIT — the §3 law);
+ *  - `settled` → `agentSettled` (no tone transition; ends the working
+ *    state and the streaming flag);
+ *  - a roster change whose LIVE view count GREW → `agentViewMounted`
+ *    (the founder's (d): content replaced the working state). Counting
+ *    growth — not presence — keeps earlier turns' lingering live views
+ *    and rehydrated history views from clearing a fresh submit's pending
+ *    window spuriously.
+ */
+export declare function bindGuueyChat(dispatch: AgentModeBinding): GuueyChatBindingProps;
+//# sourceMappingURL=bind.d.ts.map

package/dist/bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../src/bind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC5B;AAED,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;AAE/D,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,CAAC,KAAK,EAAE,2BAA2B,KAAK,IAAI,CAAC;IACzD,aAAa,EAAE,CAAC,KAAK,EAAE,SAAS,oBAAoB,EAAE,KAAK,IAAI,CAAC;CACjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,gBAAgB,GAAG,qBAAqB,CAa/E"}

package/dist/bind.js

@@ -0,0 +1,31 @@
+/**
+ * Wire a GuueyChat surface into the active-panel machine: spread the
+ * returned props onto `<GuueyChat>` (or compose them inside your own
+ * handlers — each is a plain function).
+ *
+ *  - `submit` → `agentSubmit` (tone flips ON SUBMIT — the §3 law);
+ *  - `settled` → `agentSettled` (no tone transition; ends the working
+ *    state and the streaming flag);
+ *  - a roster change whose LIVE view count GREW → `agentViewMounted`
+ *    (the founder's (d): content replaced the working state). Counting
+ *    growth — not presence — keeps earlier turns' lingering live views
+ *    and rehydrated history views from clearing a fresh submit's pending
+ *    window spuriously.
+ */
+export function bindGuueyChat(dispatch) {
+    let liveCount = 0;
+    return {
+        onActivity: (event) => {
+            if (event.type === "submit")
+                dispatch({ type: "agentSubmit" });
+            else
+                dispatch({ type: "agentSettled" });
+        },
+        onViewsChange: (views) => {
+            const next = views.filter((v) => v.origin === "live").length;
+            if (next > liveCount)
+                dispatch({ type: "agentViewMounted" });
+            liveCount = next;
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@guuey/agent-layout` — the agent-mode layout category (guuey#403).
+ *
+ * Root entry: the pure machine, the tone math, the token names, and the
+ * `@guuey/chat` bridge — everything React-free. Components live under
+ * `@guuey/agent-layout/react`; the stylesheet under
+ * `@guuey/agent-layout/styles.css`.
+ */
+export { agentModeReduce, INITIAL_AGENT_MODE_STATE, type ActivePanel, type AgentModeInput, type AgentModeState, } from "./machine.js";
+export { assertToneFloor, DEFAULT_TONES, deriveTones, hexToLab, meetsToneFloor, mixHex, toneDelta, type TonePair, } from "./tones.js";
+export { bindGuueyChat, type AgentModeBinding, type GuueyChatActivityEventShape, type GuueyChatBindingProps, type PlanViewSummaryShape, } from "./bind.js";
+/**
+ * The token vocabulary (§2) — one prefix, kebab-case, `-on` suffix keeps
+ * each tone's pair adjacent in sorted listings (platform-ruled naming).
+ * `--guuey-layout-pane-tone` is LIB-WRITTEN state: apps read it, never set
+ * it — overriding it silently breaks the category's defining behavior.
+ */
+export declare const LAYOUT_TOKENS: {
+    readonly toneUpper: "--guuey-layout-tone-upper";
+    readonly toneUpperOn: "--guuey-layout-tone-upper-on";
+    readonly toneLower: "--guuey-layout-tone-lower";
+    readonly toneLowerOn: "--guuey-layout-tone-lower-on";
+    readonly paneTone: "--guuey-layout-pane-tone";
+    readonly toneTransition: "--guuey-layout-tone-transition";
+};
+/**
+ * The follow fade — founder-certified on the ggui#633 calibration: the
+ * eased ~150ms color fade ("arrives fast, lands soft" at panel scale).
+ */
+export declare const DEFAULT_TONE_TRANSITION_MS = 150;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,eAAe,EACf,aAAa,EACb,WAAW,EACX,QAAQ,EACR,cAAc,EACd,MAAM,EACN,SAAS,EACT,KAAK,QAAQ,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,aAAa,EACb,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,WAAW,CAAC;AAEnB;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;;;;CAOhB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC"}

package/dist/index.js

@@ -0,0 +1,30 @@
+/**
+ * `@guuey/agent-layout` — the agent-mode layout category (guuey#403).
+ *
+ * Root entry: the pure machine, the tone math, the token names, and the
+ * `@guuey/chat` bridge — everything React-free. Components live under
+ * `@guuey/agent-layout/react`; the stylesheet under
+ * `@guuey/agent-layout/styles.css`.
+ */
+export { agentModeReduce, INITIAL_AGENT_MODE_STATE, } from "./machine.js";
+export { assertToneFloor, DEFAULT_TONES, deriveTones, hexToLab, meetsToneFloor, mixHex, toneDelta, } from "./tones.js";
+export { bindGuueyChat, } from "./bind.js";
+/**
+ * The token vocabulary (§2) — one prefix, kebab-case, `-on` suffix keeps
+ * each tone's pair adjacent in sorted listings (platform-ruled naming).
+ * `--guuey-layout-pane-tone` is LIB-WRITTEN state: apps read it, never set
+ * it — overriding it silently breaks the category's defining behavior.
+ */
+export const LAYOUT_TOKENS = {
+    toneUpper: "--guuey-layout-tone-upper",
+    toneUpperOn: "--guuey-layout-tone-upper-on",
+    toneLower: "--guuey-layout-tone-lower",
+    toneLowerOn: "--guuey-layout-tone-lower-on",
+    paneTone: "--guuey-layout-pane-tone",
+    toneTransition: "--guuey-layout-tone-transition",
+};
+/**
+ * The follow fade — founder-certified on the ggui#633 calibration: the
+ * eased ~150ms color fade ("arrives fast, lands soft" at panel scale).
+ */
+export const DEFAULT_TONE_TRANSITION_MS = 150;

package/dist/machine.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The active-panel machine (guuey#403 §3) — pure data-in/data-out, no React.
+ *
+ * ONE law (platform's words): **layout follows attention; transport owns
+ * the stream.** The tone tracks the user's locus of action — submit flips
+ * it ON SUBMIT (not first token, not completion), navigation flips it back,
+ * and stream end changes nothing.
+ *
+ * State beyond the panel itself (the ggui#633 calibration additions):
+ *
+ *  - `streaming` — a turn is in flight. Read by ONE rule only: closing an
+ *    agent view returns to the menu UNLESS still streaming (the console's
+ *    shipped behavior).
+ *  - `pending` — the founder's (d) requirement: on flip to the agent tone
+ *    with no view mounted yet, the pane must NEVER hold prior page content
+ *    on the agent ground — it presents the working state immediately.
+ *    `pending` arms on submit and clears on view-mount, on settle (the
+ *    answer is in the log even when no view came), and on return-to-menu.
+ *
+ * The machine is consumed through `useAgentMode()` / the Provider; this
+ * module is exported for tests and for non-React hosts that want the exact
+ * transition table.
+ */
+export type ActivePanel = "app" | "agent";
+export interface AgentModeState {
+    activePanel: ActivePanel;
+    /** A turn is in flight (submit → settled). */
+    streaming: boolean;
+    /** Working-state window: submitted, nothing presented yet (founder (d)). */
+    pending: boolean;
+}
+export declare const INITIAL_AGENT_MODE_STATE: AgentModeState;
+export type AgentModeInput = 
+/** App-side chrome interaction (NavLink click, panel focus) OR a route change. */
+{
+    type: "menuInteraction";
+}
+/** The user sent a message — the agent bridge fired. */
+ | {
+    type: "agentSubmit";
+}
+/** The turn reached `ready`. NO panel transition (platform-ruled: no bounce-back). */
+ | {
+    type: "agentSettled";
+}
+/** A live view mounted — the working state has been replaced by content. */
+ | {
+    type: "agentViewMounted";
+}
+/** The user closed an agent view (canvas "back" affordance). */
+ | {
+    type: "agentViewClosed";
+};
+/**
+ * The transition table (§3, verbatim rules). Pure; last input wins — the
+ * transition duration is the only debounce (no timers, no queue).
+ */
+export declare function agentModeReduce(state: AgentModeState, input: AgentModeInput): AgentModeState;
+//# sourceMappingURL=machine.d.ts.map

package/dist/machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../src/machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,OAAO,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,WAAW,CAAC;IACzB,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,eAAO,MAAM,wBAAwB,EAAE,cAKtC,CAAC;AAEF,MAAM,MAAM,cAAc;AACxB,kFAAkF;AAChF;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE;AAC7B,wDAAwD;GACtD;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE;AACzB,sFAAsF;GACpF;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE;AAC1B,4EAA4E;GAC1E;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE;AAC9B,gEAAgE;GAC9D;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEhC;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,GAAG,cAAc,CAkB5F"}

package/dist/machine.js

@@ -0,0 +1,52 @@
+/**
+ * The active-panel machine (guuey#403 §3) — pure data-in/data-out, no React.
+ *
+ * ONE law (platform's words): **layout follows attention; transport owns
+ * the stream.** The tone tracks the user's locus of action — submit flips
+ * it ON SUBMIT (not first token, not completion), navigation flips it back,
+ * and stream end changes nothing.
+ *
+ * State beyond the panel itself (the ggui#633 calibration additions):
+ *
+ *  - `streaming` — a turn is in flight. Read by ONE rule only: closing an
+ *    agent view returns to the menu UNLESS still streaming (the console's
+ *    shipped behavior).
+ *  - `pending` — the founder's (d) requirement: on flip to the agent tone
+ *    with no view mounted yet, the pane must NEVER hold prior page content
+ *    on the agent ground — it presents the working state immediately.
+ *    `pending` arms on submit and clears on view-mount, on settle (the
+ *    answer is in the log even when no view came), and on return-to-menu.
+ *
+ * The machine is consumed through `useAgentMode()` / the Provider; this
+ * module is exported for tests and for non-React hosts that want the exact
+ * transition table.
+ */
+export const INITIAL_AGENT_MODE_STATE = {
+    // A surface opens as the app; the agent earns the room by being addressed.
+    activePanel: "app",
+    streaming: false,
+    pending: false,
+};
+/**
+ * The transition table (§3, verbatim rules). Pure; last input wins — the
+ * transition duration is the only debounce (no timers, no queue).
+ */
+export function agentModeReduce(state, input) {
+    switch (input.type) {
+        case "menuInteraction":
+            // Re-follows the user WITHOUT touching the stream (mid-stream click
+            // included — interruption semantics live in transport, never here).
+            return { ...state, activePanel: "app", pending: false };
+        case "agentSubmit":
+            return { activePanel: "agent", streaming: true, pending: true };
+        case "agentSettled":
+            // Stream end changes nothing about the panel — the tone tracks the
+            // user's locus of action, not the agent's state.
+            return { ...state, streaming: false, pending: false };
+        case "agentViewMounted":
+            return { ...state, pending: false };
+        case "agentViewClosed":
+            // Closing a view returns to the menu UNLESS still streaming.
+            return state.streaming ? state : { ...state, activePanel: "app" };
+    }
+}

package/dist/react.d.ts

@@ -0,0 +1,109 @@
+/**
+ * `@guuey/agent-layout/react` — the Provider + primitives (guuey#403 §4).
+ * React DOM only, by design: cross-platform semantics live in
+ * `@guuey/chat`'s selection contract (portal's consult on the proposal).
+ *
+ * Engineering shape (ggui#633's scar, adopted): the active-panel state
+ * lives in its OWN provider, separate from any chat/transcript state —
+ * shells must never re-render per streaming token. The context value
+ * changes ONLY on machine transitions; every callback identity is stable.
+ */
+import { type HTMLAttributes, type ReactNode } from "react";
+import { type ActivePanel, type AgentModeInput } from "./machine.js";
+import { type TonePair } from "./tones.js";
+export interface AgentModeProviderProps {
+    children: ReactNode;
+    /**
+     * The presentation mode — the SAME host-resolved value the surface
+     * passes to `<GuueyChat mode>`; this lib rides the existing mode
+     * machinery and adds none of its own (the ggui#633 binding rule: never
+     * fixed-dark, never a second mode system). Default `"light"`, matching
+     * the kit's own default.
+     */
+    mode?: "light" | "dark";
+    /**
+     * Tone override pair for the CURRENT mode (host-palette / app-theme
+     * tiers — §2's tier chain). Validated against the perceptibility floor
+     * at wiring time (reject-under-floor, explanatory throw). Base defaults
+     * (the ggui#633 shipped pair + its dark mirror) apply when absent.
+     */
+    tones?: TonePair;
+    /** The follow fade in ms — default the founder-certified eased 150. */
+    transitionMs?: number;
+    /**
+     * The surface's identity mark (logo / brand node) for the working state
+     * (founder (d)): shown with the built-in spinner while the agent has the
+     * room but nothing is presented yet.
+     */
+    identity?: ReactNode;
+    /**
+     * The route-derived follow signal (ggui#633's scar: hand-wiring
+     * per-link missed 20+ surfaces — sub-nav tabs, in-content links,
+     * `router.push`). Pass your router's location key (`usePathname()`,
+     * `useLocation().key`, …): ANY change dispatches `menuInteraction`.
+     * The initial value dispatches nothing.
+     */
+    navigationKey?: unknown;
+}
+export declare function AgentModeProvider({ children, mode, tones, transitionMs, identity, navigationKey, }: AgentModeProviderProps): ReactNode;
+export interface UseAgentModeResult {
+    activePanel: ActivePanel;
+    /** A turn is in flight (submit → settled). */
+    streaming: boolean;
+    /** The founder-(d) working-state window is open. */
+    pending: boolean;
+    /** The raw machine door — `bindGuueyChat(dispatch)` wires a kit surface. */
+    dispatch: (input: AgentModeInput) => void;
+    /** Escape hatch for surfaces with custom needs (documented as rarely needed). */
+    setActivePanel: (panel: ActivePanel) => void;
+    /** The <1024px overlay drawer (lib-owned state; Shell renders the toggle). */
+    drawerOpen: boolean;
+    setDrawerOpen: (open: boolean) => void;
+}
+export declare function useAgentMode(): UseAgentModeResult;
+/**
+ * The grid: sidebar column + pane. Below 1024px (the console family's own
+ * sidebar boundary — one muscle memory across surfaces) the sidebar leaves
+ * the grid and becomes an overlay drawer, and the follow is SUSPENDED —
+ * the pane holds the lower (agent) tone (stylesheet-enforced; §4's ruled
+ * degraded mode). The drawer toggle renders only at drawer widths.
+ *
+ * Children: an {@link AgentModeSidebar} (wrapping the two panels) and an
+ * {@link ActivePane}. The wrapper is structural — the drawer must slide as
+ * ONE element, so the two panels share a positioned parent (the §4 sketch
+ * elides it; the contract is unchanged).
+ */
+export declare function AgentModeShell({ children, className, ...rest }: HTMLAttributes<HTMLDivElement>): ReactNode;
+/** The sidebar column: the two panels' shared, drawer-slidable parent. */
+export declare function AgentModeSidebar({ children, className, ...rest }: HTMLAttributes<HTMLElement>): ReactNode;
+export interface SidebarPanelProps extends HTMLAttributes<HTMLDivElement> {
+    section: "app" | "agent";
+}
+/**
+ * One sidebar section. `section="app"` wires `menuInteraction` on
+ * pointer/focus interactions inside it (capture-phase — apps write ZERO
+ * per-link wiring; this covers same-page clicks the route signal cannot
+ * see). `section="agent"` hosts the agent surface and wires nothing — the
+ * agent bridge speaks through the machine.
+ */
+export declare function SidebarPanel({ section, children, className, ...rest }: SidebarPanelProps): ReactNode;
+export interface ActivePaneProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Replaces the built-in working-state treatment (identity + pulse) shown
+     * while the agent has the room and nothing is presented yet (founder
+     * (d): NEVER hold prior page content on the agent ground).
+     */
+    workingState?: ReactNode;
+}
+/**
+ * The right pane: paints `--guuey-layout-pane-tone`, animates per the
+ * transition token, honors `prefers-reduced-motion` (stylesheet: instant
+ * snap). While the founder-(d) window is open the pane presents the
+ * working state INSTEAD of its children — prior page content never sits
+ * on the agent ground.
+ */
+export declare function ActivePane({ children, workingState, className, ...rest }: ActivePaneProps): ReactNode;
+export { bindGuueyChat } from "./bind.js";
+export type { AgentModeInput, AgentModeState, ActivePanel } from "./machine.js";
+export type { TonePair } from "./tones.js";
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAUL,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,cAAc,EAEpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAkC,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAa3E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,iBAAiB,CAAC,EAChC,QAAQ,EACR,IAAc,EACd,KAAK,EACL,YAAyC,EACzC,QAAe,EACf,aAAa,GACd,EAAE,sBAAsB,GAAG,SAAS,CAiDpC;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAC1C,iFAAiF;IACjF,cAAc,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IAC7C,8EAA8E;IAC9E,UAAU,EAAE,OAAO,CAAC;IACpB,aAAa,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;CACxC;AAED,wBAAgB,YAAY,IAAI,kBAAkB,CAoBjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,SAAS,EACT,GAAG,IAAI,EACR,EAAE,cAAc,CAAC,cAAc,CAAC,GAAG,SAAS,CAqB5C;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,SAAS,EACT,GAAG,IAAI,EACR,EAAE,cAAc,CAAC,WAAW,CAAC,GAAG,SAAS,CAUzC;AAED,MAAM,WAAW,iBAAkB,SAAQ,cAAc,CAAC,cAAc,CAAC;IACvE,OAAO,EAAE,KAAK,GAAG,OAAO,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,iBAAiB,GAAG,SAAS,CAcpG;AAED,MAAM,WAAW,eAAgB,SAAQ,cAAc,CAAC,cAAc,CAAC;IACrE;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,eAAe,GAAG,SAAS,CAwBrG;AAMD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChF,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/react.js

@@ -0,0 +1,121 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * `@guuey/agent-layout/react` — the Provider + primitives (guuey#403 §4).
+ * React DOM only, by design: cross-platform semantics live in
+ * `@guuey/chat`'s selection contract (portal's consult on the proposal).
+ *
+ * Engineering shape (ggui#633's scar, adopted): the active-panel state
+ * lives in its OWN provider, separate from any chat/transcript state —
+ * shells must never re-render per streaming token. The context value
+ * changes ONLY on machine transitions; every callback identity is stable.
+ */
+import { createContext, useCallback, useContext, useEffect, useMemo, useReducer, useRef, useState, } from "react";
+import { agentModeReduce, INITIAL_AGENT_MODE_STATE, } from "./machine.js";
+import { assertToneFloor, DEFAULT_TONES } from "./tones.js";
+import { DEFAULT_TONE_TRANSITION_MS, LAYOUT_TOKENS } from "./index.js";
+const AgentModeContext = createContext(null);
+export function AgentModeProvider({ children, mode = "light", tones, transitionMs = DEFAULT_TONE_TRANSITION_MS, identity = null, navigationKey, }) {
+    const [state, dispatch] = useReducer(agentModeReduce, INITIAL_AGENT_MODE_STATE);
+    const [drawerOpen, setDrawerOpen] = useState(false);
+    // Route-derived follow: any CHANGE of the key = the user navigated.
+    const navRef = useRef({ initial: true, key: navigationKey });
+    useEffect(() => {
+        if (navRef.current.initial) {
+            navRef.current = { initial: false, key: navigationKey };
+            return;
+        }
+        if (Object.is(navRef.current.key, navigationKey))
+            return;
+        navRef.current.key = navigationKey;
+        dispatch({ type: "menuInteraction" });
+        setDrawerOpen(false);
+    }, [navigationKey]);
+    const resolvedTones = useMemo(() => {
+        const pair = tones ?? DEFAULT_TONES[mode];
+        // Reject-under-floor at wiring time — an override that measures alike
+        // defeats the category (§2); the base defaults pass by construction.
+        if (tones !== undefined)
+            assertToneFloor(tones);
+        return pair;
+    }, [tones, mode]);
+    const value = useMemo(() => ({ state, dispatch, drawerOpen, setDrawerOpen, identity }), [state, drawerOpen, identity]);
+    // Token application (§2): tones + transition as inline custom properties
+    // on the shell scope; `pane-tone` is LIB-WRITTEN from the machine state.
+    const vars = {
+        [LAYOUT_TOKENS.toneUpper]: resolvedTones.upper,
+        [LAYOUT_TOKENS.toneUpperOn]: resolvedTones.upperOn,
+        [LAYOUT_TOKENS.toneLower]: resolvedTones.lower,
+        [LAYOUT_TOKENS.toneLowerOn]: resolvedTones.lowerOn,
+        [LAYOUT_TOKENS.paneTone]: state.activePanel === "agent" ? resolvedTones.lower : resolvedTones.upper,
+        [LAYOUT_TOKENS.toneTransition]: `${transitionMs}ms`,
+    };
+    return (_jsx(AgentModeContext.Provider, { value: value, children: _jsx("div", { className: "guuey-agent-layout", "data-mode": mode, "data-active-panel": state.activePanel, style: vars, children: children }) }));
+}
+export function useAgentMode() {
+    const ctx = useContext(AgentModeContext);
+    if (ctx === null) {
+        throw new Error("useAgentMode: no <AgentModeProvider> above this component.");
+    }
+    const { state, dispatch, drawerOpen, setDrawerOpen } = ctx;
+    const setActivePanel = useCallback((panel) => dispatch(panel === "app" ? { type: "menuInteraction" } : { type: "agentSubmit" }), [dispatch]);
+    return {
+        activePanel: state.activePanel,
+        streaming: state.streaming,
+        pending: state.pending,
+        dispatch,
+        setActivePanel,
+        drawerOpen,
+        setDrawerOpen,
+    };
+}
+/**
+ * The grid: sidebar column + pane. Below 1024px (the console family's own
+ * sidebar boundary — one muscle memory across surfaces) the sidebar leaves
+ * the grid and becomes an overlay drawer, and the follow is SUSPENDED —
+ * the pane holds the lower (agent) tone (stylesheet-enforced; §4's ruled
+ * degraded mode). The drawer toggle renders only at drawer widths.
+ *
+ * Children: an {@link AgentModeSidebar} (wrapping the two panels) and an
+ * {@link ActivePane}. The wrapper is structural — the drawer must slide as
+ * ONE element, so the two panels share a positioned parent (the §4 sketch
+ * elides it; the contract is unchanged).
+ */
+export function AgentModeShell({ children, className, ...rest }) {
+    const { drawerOpen, setDrawerOpen } = useAgentMode();
+    return (_jsxs("div", { ...rest, className: joinClass("guuey-layout-shell", className), "data-drawer-open": drawerOpen ? "true" : undefined, children: [_jsxs("button", { type: "button", className: "guuey-layout-drawer-toggle", "aria-expanded": drawerOpen, "aria-controls": "guuey-layout-sidebar", onClick: () => setDrawerOpen(!drawerOpen), children: [_jsx("span", { "aria-hidden": "true", children: "\u2630" }), _jsx("span", { className: "guuey-layout-sr-only", children: "Menu" })] }), children] }));
+}
+/** The sidebar column: the two panels' shared, drawer-slidable parent. */
+export function AgentModeSidebar({ children, className, ...rest }) {
+    return (_jsx("aside", { ...rest, id: "guuey-layout-sidebar", className: joinClass("guuey-layout-sidebar", className), children: children }));
+}
+/**
+ * One sidebar section. `section="app"` wires `menuInteraction` on
+ * pointer/focus interactions inside it (capture-phase — apps write ZERO
+ * per-link wiring; this covers same-page clicks the route signal cannot
+ * see). `section="agent"` hosts the agent surface and wires nothing — the
+ * agent bridge speaks through the machine.
+ */
+export function SidebarPanel({ section, children, className, ...rest }) {
+    const { dispatch } = useAgentMode();
+    const onMenuInteraction = section === "app" ? () => dispatch({ type: "menuInteraction" }) : undefined;
+    return (_jsx("div", { ...rest, className: joinClass(`guuey-layout-panel guuey-layout-panel-${section}`, className), onPointerDownCapture: onMenuInteraction, onFocusCapture: onMenuInteraction, children: children }));
+}
+/**
+ * The right pane: paints `--guuey-layout-pane-tone`, animates per the
+ * transition token, honors `prefers-reduced-motion` (stylesheet: instant
+ * snap). While the founder-(d) window is open the pane presents the
+ * working state INSTEAD of its children — prior page content never sits
+ * on the agent ground.
+ */
+export function ActivePane({ children, workingState, className, ...rest }) {
+    const ctx = useContext(AgentModeContext);
+    if (ctx === null)
+        throw new Error("ActivePane: no <AgentModeProvider> above this component.");
+    const { state, identity } = ctx;
+    const working = state.activePanel === "agent" && state.pending;
+    return (_jsx("main", { ...rest, className: joinClass("guuey-layout-pane", className), children: working ? ((workingState ?? (_jsxs("div", { className: "guuey-layout-working", role: "status", children: [identity !== null ? _jsx("div", { className: "guuey-layout-working-identity", children: identity }) : null, _jsxs("span", { className: "guuey-layout-working-pulse", "aria-hidden": "true", children: [_jsx("span", {}), _jsx("span", {}), _jsx("span", {})] }), _jsx("span", { className: "guuey-layout-sr-only", children: "Working\u2026" })] })))) : (children) }));
+}
+function joinClass(base, extra) {
+    return extra === undefined || extra === "" ? base : `${base} ${extra}`;
+}
+export { bindGuueyChat } from "./bind.js";