@guuey/agent-layout 0.16.0

package/dist/tones.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Tone math (guuey#403 §2) — the two-panel tone pair, its perceptibility
+ * floor, and the chat-palette derivation.
+ *
+ * The floor is CALIBRATED, not invented (ggui#633's scars): the console's
+ * first cut at ΔL* 3.5 measured below perception; their shipped pair
+ * (#F4F3ED warm paper vs #E4E4E2 neutral chrome) reads clearly at ΔL* 5.2
+ * because the warm→neutral TEMPERATURE step does perceptual work lightness
+ * alone doesn't. Hence the OR-form floor:
+ *
+ *     ΔL* ≥ 6  —  OR  —  a hue-temperature step (Δab ≥ 2) with ΔL* ≥ 5
+ *
+ * Both arms reject the failed 3.5 cut; the strict arm alone would have
+ * rejected the founder-certified shipped pair. The platform's theme-doc
+ * gate applies its own mirror of this rule server-side; this module is the
+ * lib's own honesty (derived defaults satisfy the floor BY CONSTRUCTION —
+ * pairs that land under it get the documented nudge apart, never a silent
+ * pass). Calibration may RAISE the floor; it does not lower it.
+ */
+/** A resolved tone pair for one mode: two backgrounds + their foregrounds. */
+export interface TonePair {
+    /** Upper panel (app menus) background. */
+    upper: string;
+    /** Foreground on the upper tone. */
+    upperOn: string;
+    /** Lower panel (agent) background. */
+    lower: string;
+    /** Foreground on the lower tone. */
+    lowerOn: string;
+}
+/**
+ * The lib base defaults — the ggui#633 SHIPPED pair for light, and its
+ * temperature-step mirror for dark (warm umber menu vs neutral chrome,
+ * ΔL* 6.5 — the strict arm). Founder-certified "two-toned and
+ * well-distinguished" in light; the dark pair keeps the identical warm→
+ * neutral grammar so a mode flip changes brightness, not the layout's
+ * character. Both pairs assert the floor in this package's tests.
+ */
+export declare const DEFAULT_TONES: Record<"light" | "dark", TonePair>;
+/** CIELAB (D65) from a `#rrggbb` hex. Throws on a malformed color. */
+export declare function hexToLab(hex: string): {
+    L: number;
+    a: number;
+    b: number;
+};
+/** The perceptibility deltas between two backgrounds. */
+export declare function toneDelta(upper: string, lower: string): {
+    dL: number;
+    dab: number;
+};
+/** The OR-form floor (module header). */
+export declare function meetsToneFloor(upper: string, lower: string): boolean;
+/**
+ * Reject-under-floor with the explanatory message (the brandAccent
+ * posture): overrides that fail perceptibility throw HERE, at wiring time,
+ * never render as an invisible seam.
+ */
+export declare function assertToneFloor(pair: TonePair): void;
+/**
+ * Base-tier derivation (§2, platform's pick): tones DERIVE from the chat
+ * palette's surface/canvas pair, so an already-themed app gets coherent
+ * tones for free — theming chat themes the layout, no second authoring
+ * step. `surface` grounds the AGENT (lower) panel — it is the chat's own
+ * ground — and `canvas` grounds the MENU (upper) panel. Pairs that land
+ * under the floor get the documented nudge: the upper tone walks away from
+ * the lower along the lightness axis (toward white below L* 50, toward
+ * black above — always INTO the pair's existing contrast direction) until
+ * the strict arm passes. Deterministic, bounded, and asserted by tests.
+ */
+export declare function deriveTones(palette: {
+    surface: string;
+    canvas: string;
+    ink: string;
+}): Pick<TonePair, "upper" | "lower"> & {
+    nudged: boolean;
+};
+/** Linear sRGB-space hex mix (`t` toward `target`). Exported for tests. */
+export declare function mixHex(base: string, target: string, t: number): string;
+//# sourceMappingURL=tones.d.ts.map

package/dist/tones.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tones.d.ts","sourceRoot":"","sources":["../src/tones.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,QAAQ;IACvB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,EAAE,QAAQ,CAa5D,CAAC;AAEF,sEAAsE;AACtE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAsBzE;AAED,yDAAyD;AACzD,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAInF;AAED,yCAAyC;AACzC,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAGpE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAQpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb,GAAG,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAe1D;AAED,2EAA2E;AAC3E,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CActE"}

package/dist/tones.js

@@ -0,0 +1,131 @@
+/**
+ * Tone math (guuey#403 §2) — the two-panel tone pair, its perceptibility
+ * floor, and the chat-palette derivation.
+ *
+ * The floor is CALIBRATED, not invented (ggui#633's scars): the console's
+ * first cut at ΔL* 3.5 measured below perception; their shipped pair
+ * (#F4F3ED warm paper vs #E4E4E2 neutral chrome) reads clearly at ΔL* 5.2
+ * because the warm→neutral TEMPERATURE step does perceptual work lightness
+ * alone doesn't. Hence the OR-form floor:
+ *
+ *     ΔL* ≥ 6  —  OR  —  a hue-temperature step (Δab ≥ 2) with ΔL* ≥ 5
+ *
+ * Both arms reject the failed 3.5 cut; the strict arm alone would have
+ * rejected the founder-certified shipped pair. The platform's theme-doc
+ * gate applies its own mirror of this rule server-side; this module is the
+ * lib's own honesty (derived defaults satisfy the floor BY CONSTRUCTION —
+ * pairs that land under it get the documented nudge apart, never a silent
+ * pass). Calibration may RAISE the floor; it does not lower it.
+ */
+/**
+ * The lib base defaults — the ggui#633 SHIPPED pair for light, and its
+ * temperature-step mirror for dark (warm umber menu vs neutral chrome,
+ * ΔL* 6.5 — the strict arm). Founder-certified "two-toned and
+ * well-distinguished" in light; the dark pair keeps the identical warm→
+ * neutral grammar so a mode flip changes brightness, not the layout's
+ * character. Both pairs assert the floor in this package's tests.
+ */
+export const DEFAULT_TONES = {
+    light: {
+        upper: "#F4F3ED",
+        upperOn: "#1F1E1B",
+        lower: "#E4E4E2",
+        lowerOn: "#1A1A1C",
+    },
+    dark: {
+        upper: "#302B24",
+        upperOn: "#ECE9E2",
+        lower: "#1E1E21",
+        lowerOn: "#E3E3E5",
+    },
+};
+/** CIELAB (D65) from a `#rrggbb` hex. Throws on a malformed color. */
+export function hexToLab(hex) {
+    const m = /^#([0-9a-fA-F]{6})$/.exec(hex.trim());
+    if (m === null) {
+        throw new Error(`agent-layout tones: "${hex}" is not a #rrggbb color — tone math needs resolvable hex (CSS keywords and var() belong to the stylesheet tier, not the derivation door).`);
+    }
+    const h = m[1];
+    const chan = (i) => parseInt(h.slice(i, i + 2), 16) / 255;
+    const lin = (c) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+    const R = lin(chan(0));
+    const G = lin(chan(2));
+    const B = lin(chan(4));
+    const X = (0.4124 * R + 0.3576 * G + 0.1805 * B) / 0.95047;
+    const Y = 0.2126 * R + 0.7152 * G + 0.0722 * B;
+    const Z = (0.0193 * R + 0.1192 * G + 0.9505 * B) / 1.08883;
+    const f = (t) => (t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116);
+    return {
+        L: 116 * f(Y) - 16,
+        a: 500 * (f(X) - f(Y)),
+        b: 200 * (f(Y) - f(Z)),
+    };
+}
+/** The perceptibility deltas between two backgrounds. */
+export function toneDelta(upper, lower) {
+    const A = hexToLab(upper);
+    const B = hexToLab(lower);
+    return { dL: Math.abs(A.L - B.L), dab: Math.hypot(A.a - B.a, A.b - B.b) };
+}
+/** The OR-form floor (module header). */
+export function meetsToneFloor(upper, lower) {
+    const { dL, dab } = toneDelta(upper, lower);
+    return dL >= 6 || (dab >= 2 && dL >= 5);
+}
+/**
+ * Reject-under-floor with the explanatory message (the brandAccent
+ * posture): overrides that fail perceptibility throw HERE, at wiring time,
+ * never render as an invisible seam.
+ */
+export function assertToneFloor(pair) {
+    if (meetsToneFloor(pair.upper, pair.lower))
+        return;
+    const { dL, dab } = toneDelta(pair.upper, pair.lower);
+    throw new Error(`agent-layout tones: the upper/lower pair ${pair.upper}/${pair.lower} is below the perceptibility floor ` +
+        `(ΔL* ${dL.toFixed(1)}, Δab ${dab.toFixed(1)}; needs ΔL* ≥ 6, or a temperature step Δab ≥ 2 with ΔL* ≥ 5). ` +
+        `Two tones that measure alike defeat the category's defining behavior — pick a stronger pair.`);
+}
+/**
+ * Base-tier derivation (§2, platform's pick): tones DERIVE from the chat
+ * palette's surface/canvas pair, so an already-themed app gets coherent
+ * tones for free — theming chat themes the layout, no second authoring
+ * step. `surface` grounds the AGENT (lower) panel — it is the chat's own
+ * ground — and `canvas` grounds the MENU (upper) panel. Pairs that land
+ * under the floor get the documented nudge: the upper tone walks away from
+ * the lower along the lightness axis (toward white below L* 50, toward
+ * black above — always INTO the pair's existing contrast direction) until
+ * the strict arm passes. Deterministic, bounded, and asserted by tests.
+ */
+export function deriveTones(palette) {
+    const lower = palette.surface;
+    let upper = palette.canvas;
+    let nudged = false;
+    if (!meetsToneFloor(upper, lower)) {
+        nudged = true;
+        const lowerL = hexToLab(lower).L;
+        // Walk upper away from lower in sRGB mix steps until ΔL* ≥ 6. The mix
+        // target keeps the walk inside the pair's own contrast direction.
+        const towardWhite = hexToLab(upper).L >= lowerL;
+        for (let i = 1; i <= 20 && !(toneDelta(upper, lower).dL >= 6); i++) {
+            upper = mixHex(palette.canvas, towardWhite ? "#FFFFFF" : "#000000", i * 0.05);
+        }
+    }
+    return { upper, lower, nudged };
+}
+/** Linear sRGB-space hex mix (`t` toward `target`). Exported for tests. */
+export function mixHex(base, target, t) {
+    const pb = /^#([0-9a-fA-F]{6})$/.exec(base.trim());
+    const pt = /^#([0-9a-fA-F]{6})$/.exec(target.trim());
+    if (pb === null || pt === null)
+        throw new Error(`agent-layout tones: mixHex needs #rrggbb inputs`);
+    const out = [0, 2, 4]
+        .map((i) => {
+        const b = parseInt(pb[1].slice(i, i + 2), 16);
+        const g = parseInt(pt[1].slice(i, i + 2), 16);
+        return Math.round(b + (g - b) * Math.min(1, Math.max(0, t)))
+            .toString(16)
+            .padStart(2, "0");
+    })
+        .join("");
+    return `#${out.toUpperCase()}`;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@guuey/agent-layout",
+  "version": "0.16.0",
+  "description": "Agent-mode layout: the two-tone shell where an app and its agent share one surface — the pane follows attention, the transport owns the stream.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/withguuey/guuey-sdks.git",
+    "directory": "packages/agent-layout"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "styles.css",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.0.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.2.7"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/bind.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 function bindGuueyChat(dispatch: AgentModeBinding): GuueyChatBindingProps {
+  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/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * `@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 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",
+} as const;
+
+/**
+ * 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/src/machine.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 const INITIAL_AGENT_MODE_STATE: AgentModeState = {
+  // A surface opens as the app; the agent earns the room by being addressed.
+  activePanel: "app",
+  streaming: false,
+  pending: false,
+};
+
+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 function agentModeReduce(state: AgentModeState, input: AgentModeInput): AgentModeState {
+  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" };
+  }
+}