@clawnify/app 0.1.1 → 0.2.1

package/dist/client/index.d.ts

@@ -0,0 +1,152 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+declare const HOST_BRIDGE_VERSION: 1;
+/** One row in the navigation. `icon` is a lucide icon name (kebab-case). */
+interface AppNavItem {
+    /** Stable identifier the host hands back on `navigate`. */
+    id: string;
+    label: string;
+    /**
+     * In-app path this item opens. Optional: a state-driven view can omit it.
+     * When present the host uses it to restore the view on reload and to make
+     * the dashboard URL shareable.
+     */
+    href?: string;
+    /** Icon name from TILE_ICONS, e.g. "layout-dashboard". Unknown names render a dot. */
+    icon?: string;
+    /** Live badge, e.g. items waiting. Omit for none. */
+    count?: number;
+    /**
+     * The app's home screen. Not listed as a row: standalone the brand row
+     * opens it, and in the dashboard the app's own header does. One per app.
+     */
+    home?: boolean;
+    /**
+     * Tile colour for this section. Sections are the records inside an app,
+     * so they draw as a small coloured tile with a white glyph (the app itself
+     * is navigation and stays an outline glyph). One of `NAV_COLORS`; omitted
+     * = picked from the palette by `id`, stable across renders and hosts.
+     */
+    color?: NavColor;
+}
+/** The section tile palette, shared by the standalone sidebar and the dashboard. */
+declare const NAV_COLORS: {
+    readonly red: "#ef4444";
+    readonly orange: "#f97514";
+    readonly amber: "#f59e0b";
+    readonly green: "#22c55e";
+    readonly sky: "#17bde9";
+    readonly blue: "#266df0";
+    readonly violet: "#8b5cf6";
+    readonly pink: "#ec4899";
+};
+type NavColor = keyof typeof NAV_COLORS;
+/** Deterministic palette pick for an item without an explicit colour. */
+declare function navColorFor(id: string): NavColor;
+/**
+ * The icon library: the names the Clawnify dashboard can draw for an app
+ * and its sections (resolved to the Phosphor set in both sidebars). Pick
+ * from these; the apps AGENTS.md lists them by meaning.
+ */
+declare const TILE_ICONS: readonly ["activity", "archive", "bar-chart-3", "bell", "book-open", "bot", "briefcase", "building-2", "calendar", "calendar-days", "camera", "check-square", "clipboard-list", "clock", "code-2", "contact", "credit-card", "database", "dollar-sign", "file", "file-text", "folder", "globe", "hash", "history", "home", "image", "inbox", "kanban", "layers", "layout-dashboard", "layout-grid", "link", "list", "list-checks", "mail", "map", "message-square", "mic", "package", "phone", "pie-chart", "play", "search", "send", "settings", "shopping-cart", "sparkles", "star", "table", "tag", "target", "truck", "upload", "user", "users", "video", "wallet", "zap"];
+type TileIconName = (typeof TILE_ICONS)[number];
+interface TileIconProps {
+    /** Icon name from TILE_ICONS. Unknown or missing = a small dot. */
+    icon?: string;
+    /** Palette colour. Omitted = picked from `seed` (or `icon`) by hash. */
+    color?: NavColor;
+    /** Stable string the colour is derived from when `color` is not given. */
+    seed?: string;
+    /** Tile edge in px. The glyph scales with it. Default 16. */
+    size?: number;
+    className?: string;
+    title?: string;
+}
+/**
+ * The record tile: a small rounded square in a palette colour with a white
+ * lucide glyph. The sidebar draws every app section with it; apps can use
+ * the same tile anywhere a record type needs an identity mark (table rows,
+ * cards, pickers) so the two surfaces stay one system. Self-contained inline
+ * styles, so it works outside <AppNav> and in any stylesheet setup.
+ *
+ *   <TileIcon icon="users" color="blue" />
+ *   <TileIcon icon="phone" seed={lead.id} size={20} />
+ */
+declare function TileIcon({ icon, color, seed, size, className, title }: TileIconProps): react.JSX.Element;
+interface AppNavGroup {
+    /** Eyebrow shown above the items. Omit for an unlabelled group. */
+    label?: string;
+    items: AppNavItem[];
+}
+type AppToHostMessage = {
+    source: "clawnify-app";
+    v: 1;
+    type: "ready";
+} | {
+    source: "clawnify-app";
+    v: 1;
+    type: "nav";
+    title: string;
+    /** lucide icon name for the app itself. */
+    icon?: string;
+    groups: AppNavGroup[];
+    active?: string;
+} | {
+    source: "clawnify-app";
+    v: 1;
+    type: "location";
+    path: string;
+};
+type HostToAppMessage = {
+    source: "clawnify-host";
+    v: 1;
+    type: "hello";
+} | {
+    source: "clawnify-host";
+    v: 1;
+    type: "navigate";
+    id: string;
+};
+/**
+ * Whether this page is running inside the Clawnify dashboard. Computed once at
+ * module load — the query parameter is only on the initial URL — and remembered
+ * for the tab so in-iframe full navigations keep the mode.
+ */
+declare const embedded: boolean;
+/**
+ * Tell the host where the app is, so the dashboard URL can restore this view
+ * on reload. Call it whenever your router's location changes; a no-op when
+ * standalone.
+ */
+declare function reportLocation(path: string): void;
+interface AppNavProps {
+    /** App name, shown in the brand row standalone and in the host's switcher. */
+    title: string;
+    /**
+     * The app's own glyph, a lucide icon name (kebab-case). Drawn as an
+     * outline icon with no background: in the standalone brand row, and by the
+     * dashboard on the app's sidebar item. Tiles are for records, not for
+     * navigation, so the app's coloured tile icon stays out of the sidebar.
+     */
+    icon?: string;
+    groups: AppNavGroup[];
+    /** `id` of the active item. */
+    active?: string;
+    /** Called with the item the user chose, from either renderer. */
+    onNavigate: (item: AppNavItem) => void;
+    /** Rendered at the bottom of the standalone sidebar (a footer action, say). */
+    children?: ReactNode;
+}
+/**
+ * The app's navigation: sidebar when standalone, host-fed when embedded.
+ *
+ * Standalone layout: the sidebar is a 260px column at ≥768px and a horizontal
+ * strip below that, so put it first inside a `flex flex-col md:flex-row`
+ * container. It paints with the app's own theme tokens (`--surface`,
+ * `--border`, `--primary`…) and falls back to the platform defaults when a
+ * token is missing.
+ */
+declare function AppNav({ title, icon, groups, active, onNavigate, children }: AppNavProps): react.JSX.Element | null;
+
+export { AppNav, type AppNavGroup, type AppNavItem, type AppNavProps, type AppToHostMessage, HOST_BRIDGE_VERSION, type HostToAppMessage, NAV_COLORS, type NavColor, TILE_ICONS, TileIcon, type TileIconName, type TileIconProps, embedded, navColorFor, reportLocation };

package/dist/client/index.js

@@ -0,0 +1,419 @@
+// src/client/index.tsx
+import {
+  useEffect,
+  useRef
+} from "react";
+import {
+  AddressBook,
+  Archive,
+  Bell,
+  BookOpen,
+  Briefcase,
+  Building,
+  Calendar,
+  CalendarDots,
+  Camera,
+  ChartBar,
+  ChartPie,
+  ChatCircle,
+  CheckSquare,
+  ClipboardText,
+  Clock,
+  ClockCounterClockwise,
+  Code,
+  CreditCard,
+  CurrencyDollar,
+  Database,
+  Envelope,
+  File,
+  FileText,
+  Folder,
+  Gear,
+  Globe,
+  GridFour,
+  Hash,
+  House,
+  Image,
+  Kanban,
+  Lightning,
+  Link,
+  List,
+  ListChecks,
+  MagnifyingGlass,
+  MapTrifold,
+  Microphone,
+  Package,
+  PaperPlaneTilt,
+  Phone,
+  Play,
+  Pulse,
+  Robot,
+  ShoppingCart,
+  Sparkle,
+  SquaresFour,
+  Stack,
+  Star,
+  Table,
+  Tag,
+  Target,
+  Tray,
+  Truck,
+  Upload,
+  User,
+  VideoCamera,
+  Wallet
+} from "@phosphor-icons/react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var HOST_BRIDGE_VERSION = 1;
+var NAV_COLORS = {
+  red: "#ef4444",
+  orange: "#f97514",
+  amber: "#f59e0b",
+  green: "#22c55e",
+  sky: "#17bde9",
+  blue: "#266df0",
+  violet: "#8b5cf6",
+  pink: "#ec4899"
+};
+function navColorFor(id) {
+  const names = Object.keys(NAV_COLORS);
+  let h = 0;
+  for (let i = 0; i < id.length; i++) h = h * 31 + id.charCodeAt(i) >>> 0;
+  return names[h % names.length];
+}
+var TILE_ICONS = [
+  "activity",
+  "archive",
+  "bar-chart-3",
+  "bell",
+  "book-open",
+  "bot",
+  "briefcase",
+  "building-2",
+  "calendar",
+  "calendar-days",
+  "camera",
+  "check-square",
+  "clipboard-list",
+  "clock",
+  "code-2",
+  "contact",
+  "credit-card",
+  "database",
+  "dollar-sign",
+  "file",
+  "file-text",
+  "folder",
+  "globe",
+  "hash",
+  "history",
+  "home",
+  "image",
+  "inbox",
+  "kanban",
+  "layers",
+  "layout-dashboard",
+  "layout-grid",
+  "link",
+  "list",
+  "list-checks",
+  "mail",
+  "map",
+  "message-square",
+  "mic",
+  "package",
+  "phone",
+  "pie-chart",
+  "play",
+  "search",
+  "send",
+  "settings",
+  "shopping-cart",
+  "sparkles",
+  "star",
+  "table",
+  "tag",
+  "target",
+  "truck",
+  "upload",
+  "user",
+  "users",
+  "video",
+  "wallet",
+  "zap"
+];
+function TileIcon({ icon, color, seed, size = 16, className, title }) {
+  const fill = NAV_COLORS[color ?? navColorFor(seed ?? icon ?? "")];
+  const glyph = Math.round(size * 0.7);
+  return /* @__PURE__ */ jsx(
+    "span",
+    {
+      className,
+      title,
+      "aria-hidden": title ? void 0 : true,
+      style: {
+        display: "inline-flex",
+        width: size,
+        height: size,
+        flexShrink: 0,
+        alignItems: "center",
+        justifyContent: "center",
+        borderRadius: "30%",
+        border: "1px solid rgb(0 0 0 / 0.06)",
+        background: fill,
+        color: "#fff"
+      },
+      children: iconFor(icon) ? (() => {
+        const I = iconFor(icon);
+        return /* @__PURE__ */ jsx(I, { size: glyph, weight: "fill", "aria-hidden": true });
+      })() : /* @__PURE__ */ jsx("span", { style: { width: glyph * 0.6, height: glyph * 0.6, borderRadius: 9999, background: "currentColor" } })
+    }
+  );
+}
+var HOST_PARAM = "clawnify_host";
+var STORAGE_KEY = "clawnify_host";
+var embedded = (() => {
+  if (typeof window === "undefined") return false;
+  if (window.parent === window) return false;
+  let flagged = false;
+  try {
+    flagged = new URLSearchParams(window.location.search).get(HOST_PARAM) === "1";
+    if (flagged) window.sessionStorage.setItem(STORAGE_KEY, "1");
+    else flagged = window.sessionStorage.getItem(STORAGE_KEY) === "1";
+  } catch {
+  }
+  return flagged;
+})();
+function post(message) {
+  if (!embedded) return;
+  window.parent.postMessage(message, "*");
+}
+function reportLocation(path) {
+  let clean = path;
+  try {
+    const u = new URL(path, "http://app.invalid");
+    u.searchParams.delete("token");
+    u.searchParams.delete(HOST_PARAM);
+    clean = u.pathname + u.search + u.hash;
+  } catch {
+  }
+  post({ source: "clawnify-app", v: HOST_BRIDGE_VERSION, type: "location", path: clean });
+}
+function AppNav({ title, icon, groups, active, onNavigate, children }) {
+  const onNavigateRef = useRef(onNavigate);
+  onNavigateRef.current = onNavigate;
+  const groupsRef = useRef(groups);
+  groupsRef.current = groups;
+  const payload = embedded ? JSON.stringify({ title, icon, groups: sanitize(groups), active }) : "";
+  const lastSent = useRef("");
+  useEffect(() => {
+    if (!embedded || payload === lastSent.current) return;
+    lastSent.current = payload;
+    const { title: title2, icon: icon2, groups: groups2, active: active2 } = JSON.parse(payload);
+    post({ source: "clawnify-app", v: HOST_BRIDGE_VERSION, type: "nav", title: title2, icon: icon2, groups: groups2, active: active2 });
+  }, [payload]);
+  useEffect(() => {
+    if (!embedded) return;
+    function onMessage(e) {
+      if (e.source !== window.parent) return;
+      const d = e.data;
+      if (!d || d.source !== "clawnify-host" || d.v !== HOST_BRIDGE_VERSION) return;
+      if (d.type === "hello") {
+        lastSent.current = "";
+        const g = sanitize(groupsRef.current);
+        post({ source: "clawnify-app", v: HOST_BRIDGE_VERSION, type: "nav", title, icon, groups: g, active });
+      } else if (d.type === "navigate" && typeof d.id === "string") {
+        const item = groupsRef.current.flatMap((g) => g.items).find((i) => i.id === d.id);
+        if (item) onNavigateRef.current(item);
+      }
+    }
+    window.addEventListener("message", onMessage);
+    post({ source: "clawnify-app", v: HOST_BRIDGE_VERSION, type: "ready" });
+    return () => window.removeEventListener("message", onMessage);
+  }, []);
+  if (embedded) return null;
+  const home = groups.flatMap((g) => g.items).find((i) => i.home);
+  const brand = /* @__PURE__ */ jsxs(Fragment, { children: [
+    (() => {
+      const I = iconFor(icon);
+      return I ? /* @__PURE__ */ jsx(I, { size: 16, "aria-hidden": true }) : null;
+    })(),
+    /* @__PURE__ */ jsx("span", { children: title })
+  ] });
+  return /* @__PURE__ */ jsxs("aside", { className: "cn-nav", children: [
+    /* @__PURE__ */ jsx("style", { children: CSS }),
+    home ? /* @__PURE__ */ jsx(
+      "a",
+      {
+        href: home.href ?? "/",
+        className: "cn-nav-brand",
+        "data-active": home.id === active || void 0,
+        "aria-current": home.id === active ? "page" : void 0,
+        onClick: (e) => {
+          if (e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0) return;
+          e.preventDefault();
+          onNavigate(home);
+        },
+        children: brand
+      }
+    ) : /* @__PURE__ */ jsx("div", { className: "cn-nav-brand", children: brand }),
+    /* @__PURE__ */ jsx("nav", { className: "cn-nav-groups", "aria-label": "Primary", children: groups.map((g, gi) => /* @__PURE__ */ jsxs("div", { className: "cn-nav-group", children: [
+      g.label && /* @__PURE__ */ jsx("p", { className: "cn-nav-eyebrow", children: g.label }),
+      g.items.filter((item) => !item.home).map((item) => /* @__PURE__ */ jsx(NavRow, { item, active: item.id === active, onNavigate }, item.id))
+    ] }, g.label ?? gi)) }),
+    children && /* @__PURE__ */ jsx("div", { className: "cn-nav-footer", children })
+  ] });
+}
+function NavRow({
+  item,
+  active,
+  onNavigate
+}) {
+  const body = /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(TileIcon, { icon: item.icon, color: item.color, seed: item.id }),
+    /* @__PURE__ */ jsx("span", { className: "cn-nav-label", children: item.label }),
+    typeof item.count === "number" && /* @__PURE__ */ jsx("span", { className: "cn-nav-count", children: item.count })
+  ] });
+  if (item.href) {
+    return /* @__PURE__ */ jsx(
+      "a",
+      {
+        href: item.href,
+        className: "cn-nav-item",
+        "data-active": active || void 0,
+        "aria-current": active ? "page" : void 0,
+        onClick: (e) => {
+          if (e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0) return;
+          e.preventDefault();
+          onNavigate(item);
+        },
+        children: body
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      className: "cn-nav-item",
+      "data-active": active || void 0,
+      "aria-current": active ? "page" : void 0,
+      onClick: () => onNavigate(item),
+      children: body
+    }
+  );
+}
+var ICONS = {
+  "activity": Pulse,
+  "archive": Archive,
+  "bar-chart-3": ChartBar,
+  "bell": Bell,
+  "book-open": BookOpen,
+  "bot": Robot,
+  "briefcase": Briefcase,
+  "building-2": Building,
+  "calendar": Calendar,
+  "calendar-days": CalendarDots,
+  "camera": Camera,
+  "check-square": CheckSquare,
+  "clipboard-list": ClipboardText,
+  "clock": Clock,
+  "code-2": Code,
+  "contact": AddressBook,
+  "credit-card": CreditCard,
+  "database": Database,
+  "dollar-sign": CurrencyDollar,
+  "file": File,
+  "file-text": FileText,
+  "folder": Folder,
+  "globe": Globe,
+  "hash": Hash,
+  "history": ClockCounterClockwise,
+  "home": House,
+  "image": Image,
+  "inbox": Tray,
+  "kanban": Kanban,
+  "layers": Stack,
+  "layout-dashboard": SquaresFour,
+  "layout-grid": GridFour,
+  "link": Link,
+  "list": List,
+  "list-checks": ListChecks,
+  "mail": Envelope,
+  "map": MapTrifold,
+  "message-square": ChatCircle,
+  "mic": Microphone,
+  "package": Package,
+  "phone": Phone,
+  "pie-chart": ChartPie,
+  "play": Play,
+  "search": MagnifyingGlass,
+  "send": PaperPlaneTilt,
+  "settings": Gear,
+  "shopping-cart": ShoppingCart,
+  "sparkles": Sparkle,
+  "star": Star,
+  "table": Table,
+  "tag": Tag,
+  "target": Target,
+  "truck": Truck,
+  "upload": Upload,
+  "user": User,
+  "users": User,
+  "video": VideoCamera,
+  "wallet": Wallet,
+  "zap": Lightning
+};
+function iconFor(name) {
+  return name ? ICONS[name] : void 0;
+}
+function sanitize(groups) {
+  return groups.slice(0, 20).map((g) => ({
+    ...g.label ? { label: String(g.label).slice(0, 40) } : {},
+    items: g.items.slice(0, 100).map((i) => ({
+      id: String(i.id),
+      label: String(i.label).slice(0, 60),
+      ...i.href ? { href: String(i.href) } : {},
+      ...i.icon ? { icon: String(i.icon) } : {},
+      ...typeof i.count === "number" && Number.isFinite(i.count) ? { count: i.count } : {},
+      ...i.home ? { home: true } : {},
+      ...i.color && i.color in NAV_COLORS ? { color: i.color } : {}
+    }))
+  }));
+}
+var CSS = `
+.cn-nav{width:16.25rem;flex-shrink:0;display:flex;flex-direction:column;border-right:1px solid var(--border,#e2e8f0);background:var(--surface,#fff);color:var(--foreground,#1a202c)}
+.cn-nav-brand{height:3.5rem;flex-shrink:0;display:flex;align-items:center;gap:.5rem;padding:0 1.25rem;border-bottom:1px solid var(--border,#e2e8f0);font-size:.875rem;font-weight:600;color:inherit;text-decoration:none}
+a.cn-nav-brand:hover{background:var(--sunken,#f1f5f9)}
+.cn-nav-brand>svg{color:var(--primary,#dd5164)}
+.cn-nav-groups{flex:1;overflow-y:auto;padding:.75rem}
+.cn-nav-group+.cn-nav-group{margin-top:1rem}
+.cn-nav-eyebrow{margin:0 0 .25rem;padding:0 .625rem;font-size:.75rem;font-weight:500;color:var(--muted,#475569)}
+.cn-nav-item{display:flex;align-items:center;gap:.5rem;width:100%;margin:0 0 .125rem;padding:.4375rem .625rem;border:0;border-radius:.375rem;background:none;color:inherit;font:inherit;font-size:.875rem;text-align:left;text-decoration:none;cursor:pointer}
+.cn-nav-item:hover{background:var(--sunken,#f1f5f9)}
+.cn-nav-item[data-active]{background:color-mix(in srgb,var(--primary,#dd5164) 12%,transparent);color:var(--primary,#dd5164);font-weight:600}
+.cn-nav-item:focus-visible{outline:2px solid var(--ring,#2563eb);outline-offset:-2px}
+.cn-nav-label{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.cn-nav-count{font-size:.75rem;font-variant-numeric:tabular-nums;color:var(--muted,#475569)}
+.cn-nav-item[data-active] .cn-nav-count{color:inherit}
+.cn-nav-footer{padding:.75rem;border-top:1px solid var(--border,#e2e8f0)}
+@media (max-width:767px){
+.cn-nav{width:100%;flex-direction:row;border-right:0;border-bottom:1px solid var(--border,#e2e8f0)}
+.cn-nav-brand,.cn-nav-eyebrow,.cn-nav-footer{display:none}
+.cn-nav-groups{display:flex;gap:.25rem;padding:.5rem .75rem;overflow-x:auto;overflow-y:hidden}
+.cn-nav-group{display:flex;gap:.25rem}
+.cn-nav-group+.cn-nav-group{margin:0}
+.cn-nav-item{width:auto;margin:0;white-space:nowrap}
+}
+`;
+export {
+  AppNav,
+  HOST_BRIDGE_VERSION,
+  NAV_COLORS,
+  TILE_ICONS,
+  TileIcon,
+  embedded,
+  navColorFor,
+  reportLocation
+};
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/index.tsx"],"sourcesContent":["/**\n * @clawnify/app/client — the host bridge for a Clawnify app's browser side.\n *\n * A Clawnify app is a full page on its own origin. Opened directly (local\n * `pnpm dev`, or `<slug>.apps.clawnify.com`) it renders its own sidebar.\n * Opened inside the Clawnify dashboard it sits in an iframe, and the dashboard\n * wants to render that same navigation in ITS sidebar so the user sees one\n * nav, not two.\n *\n * `<AppNav>` is the one definition of the app's navigation that serves both:\n *\n *   • standalone → it draws the app's sidebar (desktop rail, mobile strip)\n *   • embedded   → it draws nothing and posts the nav tree to the host over\n *                  `postMessage`; the host renders it and posts `navigate`\n *                  back when the user clicks.\n *\n * Nothing about the app changes between the two: same router, same screens,\n * same data. Only who paints the list of links.\n *\n *   import { AppNav, reportLocation } from \"@clawnify/app/client\";\n *\n *   <AppNav\n *     title=\"OpenDialer\"\n *     icon=\"phone\"\n *     groups={[{ label: \"Work\", items: [\n *       { id: \"dashboard\", label: \"Dashboard\", href: \"/\", home: true },\n *       { id: \"leads\", label: \"Leads\", href: \"/leads\", icon: \"users\", count: 12 },\n *     ]}]}\n *     active=\"leads\"\n *     onNavigate={(item) => navigate(item.href!)}\n *   />\n *\n * Re-render with a new `groups` / `active` and the host sidebar updates in\n * the same tick — counts are just a field, so \"Leads 12\" becomes \"Leads 11\"\n * the moment your own state does. No polling, no endpoint.\n *\n * Embedding is detected from the `clawnify_host=1` query parameter the\n * dashboard appends to the iframe URL, remembered in sessionStorage so a\n * full-page navigation inside the iframe stays in embedded mode. A page that\n * is iframed by anything else, or opened directly, is \"standalone\".\n *\n * Protocol (versioned, additive — `nav` and `location` are the first\n * message types; more host surfaces can ride the same channel later):\n *\n *   app  → host   { source: \"clawnify-app\",  v: 1, type: \"ready\" }\n *                 { source: \"clawnify-app\",  v: 1, type: \"nav\", title, icon?, groups, active? }\n *                 { source: \"clawnify-app\",  v: 1, type: \"location\", path }\n *   host → app    { source: \"clawnify-host\", v: 1, type: \"hello\" }\n *                 { source: \"clawnify-host\", v: 1, type: \"navigate\", id }\n */\nimport {\n  useEffect,\n  useRef,\n  type MouseEvent,\n  type ReactNode,\n} from \"react\";\nimport {\n  AddressBook,\n  Archive,\n  Bell,\n  BookOpen,\n  Briefcase,\n  Building,\n  Calendar,\n  CalendarDots,\n  Camera,\n  ChartBar,\n  ChartPie,\n  ChatCircle,\n  CheckSquare,\n  ClipboardText,\n  Clock,\n  ClockCounterClockwise,\n  Code,\n  CreditCard,\n  CurrencyDollar,\n  Database,\n  Envelope,\n  File,\n  FileText,\n  Folder,\n  Gear,\n  Globe,\n  GridFour,\n  Hash,\n  House,\n  Image,\n  Kanban,\n  Lightning,\n  Link,\n  List,\n  ListChecks,\n  MagnifyingGlass,\n  MapTrifold,\n  Microphone,\n  Package,\n  PaperPlaneTilt,\n  Phone,\n  Play,\n  Pulse,\n  Robot,\n  ShoppingCart,\n  Sparkle,\n  SquaresFour,\n  Stack,\n  Star,\n  Table,\n  Tag,\n  Target,\n  Tray,\n  Truck,\n  Upload,\n  User,\n  VideoCamera,\n  Wallet,\n  type Icon as PhosphorIcon,\n} from \"@phosphor-icons/react\";\n\nexport const HOST_BRIDGE_VERSION = 1 as const;\n\n/** One row in the navigation. `icon` is a lucide icon name (kebab-case). */\nexport interface AppNavItem {\n  /** Stable identifier the host hands back on `navigate`. */\n  id: string;\n  label: string;\n  /**\n   * In-app path this item opens. Optional: a state-driven view can omit it.\n   * When present the host uses it to restore the view on reload and to make\n   * the dashboard URL shareable.\n   */\n  href?: string;\n  /** Icon name from TILE_ICONS, e.g. \"layout-dashboard\". Unknown names render a dot. */\n  icon?: string;\n  /** Live badge, e.g. items waiting. Omit for none. */\n  count?: number;\n  /**\n   * The app's home screen. Not listed as a row: standalone the brand row\n   * opens it, and in the dashboard the app's own header does. One per app.\n   */\n  home?: boolean;\n  /**\n   * Tile colour for this section. Sections are the records inside an app,\n   * so they draw as a small coloured tile with a white glyph (the app itself\n   * is navigation and stays an outline glyph). One of `NAV_COLORS`; omitted\n   * = picked from the palette by `id`, stable across renders and hosts.\n   */\n  color?: NavColor;\n}\n\n/** The section tile palette, shared by the standalone sidebar and the dashboard. */\nexport const NAV_COLORS = {\n  red: \"#ef4444\",\n  orange: \"#f97514\",\n  amber: \"#f59e0b\",\n  green: \"#22c55e\",\n  sky: \"#17bde9\",\n  blue: \"#266df0\",\n  violet: \"#8b5cf6\",\n  pink: \"#ec4899\",\n} as const;\nexport type NavColor = keyof typeof NAV_COLORS;\n\n/** Deterministic palette pick for an item without an explicit colour. */\nexport function navColorFor(id: string): NavColor {\n  const names = Object.keys(NAV_COLORS) as NavColor[];\n  let h = 0;\n  for (let i = 0; i < id.length; i++) h = (h * 31 + id.charCodeAt(i)) >>> 0;\n  return names[h % names.length];\n}\n\n/**\n * The icon library: the names the Clawnify dashboard can draw for an app\n * and its sections (resolved to the Phosphor set in both sidebars). Pick\n * from these; the apps AGENTS.md lists them by meaning.\n */\nexport const TILE_ICONS = [\n  \"activity\",\n  \"archive\",\n  \"bar-chart-3\",\n  \"bell\",\n  \"book-open\",\n  \"bot\",\n  \"briefcase\",\n  \"building-2\",\n  \"calendar\",\n  \"calendar-days\",\n  \"camera\",\n  \"check-square\",\n  \"clipboard-list\",\n  \"clock\",\n  \"code-2\",\n  \"contact\",\n  \"credit-card\",\n  \"database\",\n  \"dollar-sign\",\n  \"file\",\n  \"file-text\",\n  \"folder\",\n  \"globe\",\n  \"hash\",\n  \"history\",\n  \"home\",\n  \"image\",\n  \"inbox\",\n  \"kanban\",\n  \"layers\",\n  \"layout-dashboard\",\n  \"layout-grid\",\n  \"link\",\n  \"list\",\n  \"list-checks\",\n  \"mail\",\n  \"map\",\n  \"message-square\",\n  \"mic\",\n  \"package\",\n  \"phone\",\n  \"pie-chart\",\n  \"play\",\n  \"search\",\n  \"send\",\n  \"settings\",\n  \"shopping-cart\",\n  \"sparkles\",\n  \"star\",\n  \"table\",\n  \"tag\",\n  \"target\",\n  \"truck\",\n  \"upload\",\n  \"user\",\n  \"users\",\n  \"video\",\n  \"wallet\",\n  \"zap\",\n] as const;\nexport type TileIconName = (typeof TILE_ICONS)[number];\n\nexport interface TileIconProps {\n  /** Icon name from TILE_ICONS. Unknown or missing = a small dot. */\n  icon?: string;\n  /** Palette colour. Omitted = picked from `seed` (or `icon`) by hash. */\n  color?: NavColor;\n  /** Stable string the colour is derived from when `color` is not given. */\n  seed?: string;\n  /** Tile edge in px. The glyph scales with it. Default 16. */\n  size?: number;\n  className?: string;\n  title?: string;\n}\n\n/**\n * The record tile: a small rounded square in a palette colour with a white\n * lucide glyph. The sidebar draws every app section with it; apps can use\n * the same tile anywhere a record type needs an identity mark (table rows,\n * cards, pickers) so the two surfaces stay one system. Self-contained inline\n * styles, so it works outside <AppNav> and in any stylesheet setup.\n *\n *   <TileIcon icon=\"users\" color=\"blue\" />\n *   <TileIcon icon=\"phone\" seed={lead.id} size={20} />\n */\nexport function TileIcon({ icon, color, seed, size = 16, className, title }: TileIconProps) {\n  const fill = NAV_COLORS[color ?? navColorFor(seed ?? icon ?? \"\")];\n  // The glyph box is 0.7 of the tile: Phosphor draws on ~224 of its 256\n  // units, so the visible glyph lands near 60% of the tile with clear\n  // padding around it, solid white — Attio's record-tile proportion.\n  const glyph = Math.round(size * 0.7);\n  return (\n    <span\n      className={className}\n      title={title}\n      aria-hidden={title ? undefined : true}\n      style={{\n        display: \"inline-flex\",\n        width: size,\n        height: size,\n        flexShrink: 0,\n        alignItems: \"center\",\n        justifyContent: \"center\",\n        borderRadius: \"30%\",\n        border: \"1px solid rgb(0 0 0 / 0.06)\",\n        background: fill,\n        color: \"#fff\",\n      }}\n    >\n      {iconFor(icon) ? (\n        (() => { const I = iconFor(icon)!; return <I size={glyph} weight=\"fill\" aria-hidden />; })()\n      ) : (\n        <span style={{ width: glyph * 0.6, height: glyph * 0.6, borderRadius: 9999, background: \"currentColor\" }} />\n      )}\n    </span>\n  );\n}\n\nexport interface AppNavGroup {\n  /** Eyebrow shown above the items. Omit for an unlabelled group. */\n  label?: string;\n  items: AppNavItem[];\n}\n\nexport type AppToHostMessage =\n  | { source: \"clawnify-app\"; v: 1; type: \"ready\" }\n  | {\n      source: \"clawnify-app\";\n      v: 1;\n      type: \"nav\";\n      title: string;\n      /** lucide icon name for the app itself. */\n      icon?: string;\n      groups: AppNavGroup[];\n      active?: string;\n    }\n  | { source: \"clawnify-app\"; v: 1; type: \"location\"; path: string };\n\nexport type HostToAppMessage =\n  | { source: \"clawnify-host\"; v: 1; type: \"hello\" }\n  | { source: \"clawnify-host\"; v: 1; type: \"navigate\"; id: string };\n\nconst HOST_PARAM = \"clawnify_host\";\nconst STORAGE_KEY = \"clawnify_host\";\n\n/**\n * Whether this page is running inside the Clawnify dashboard. Computed once at\n * module load — the query parameter is only on the initial URL — and remembered\n * for the tab so in-iframe full navigations keep the mode.\n */\nexport const embedded: boolean = (() => {\n  if (typeof window === \"undefined\") return false;\n  if (window.parent === window) return false;\n  let flagged = false;\n  try {\n    flagged = new URLSearchParams(window.location.search).get(HOST_PARAM) === \"1\";\n    if (flagged) window.sessionStorage.setItem(STORAGE_KEY, \"1\");\n    else flagged = window.sessionStorage.getItem(STORAGE_KEY) === \"1\";\n  } catch {\n    // Storage can throw in a partitioned or locked-down iframe; the query\n    // parameter alone still decides for this document.\n  }\n  return flagged;\n})();\n\nfunction post(message: AppToHostMessage) {\n  if (!embedded) return;\n  // The dashboard may live on app.clawnify.com or a white-label domain, so the\n  // app cannot pin the target origin. The payload is navigation labels and a\n  // path — nothing secret — and the host verifies the sender is its own iframe.\n  window.parent.postMessage(message, \"*\");\n}\n\n/**\n * Tell the host where the app is, so the dashboard URL can restore this view\n * on reload. Call it whenever your router's location changes; a no-op when\n * standalone.\n */\nexport function reportLocation(path: string) {\n  // The initial URL carries the dashboard's own parameters (the app token\n  // and the host flag). They are not part of the app's location and must\n  // never land in a URL the dashboard writes, so strip them here as well.\n  let clean = path;\n  try {\n    const u = new URL(path, \"http://app.invalid\");\n    u.searchParams.delete(\"token\");\n    u.searchParams.delete(HOST_PARAM);\n    clean = u.pathname + u.search + u.hash;\n  } catch {\n    // Not a path we can parse: send as-is, the host validates its shape.\n  }\n  post({ source: \"clawnify-app\", v: HOST_BRIDGE_VERSION, type: \"location\", path: clean });\n}\n\nexport interface AppNavProps {\n  /** App name, shown in the brand row standalone and in the host's switcher. */\n  title: string;\n  /**\n   * The app's own glyph, a lucide icon name (kebab-case). Drawn as an\n   * outline icon with no background: in the standalone brand row, and by the\n   * dashboard on the app's sidebar item. Tiles are for records, not for\n   * navigation, so the app's coloured tile icon stays out of the sidebar.\n   */\n  icon?: string;\n  groups: AppNavGroup[];\n  /** `id` of the active item. */\n  active?: string;\n  /** Called with the item the user chose, from either renderer. */\n  onNavigate: (item: AppNavItem) => void;\n  /** Rendered at the bottom of the standalone sidebar (a footer action, say). */\n  children?: ReactNode;\n}\n\n/**\n * The app's navigation: sidebar when standalone, host-fed when embedded.\n *\n * Standalone layout: the sidebar is a 260px column at ≥768px and a horizontal\n * strip below that, so put it first inside a `flex flex-col md:flex-row`\n * container. It paints with the app's own theme tokens (`--surface`,\n * `--border`, `--primary`…) and falls back to the platform defaults when a\n * token is missing.\n */\nexport function AppNav({ title, icon, groups, active, onNavigate, children }: AppNavProps) {\n  // Always the latest callback, so the host listener never calls a stale one.\n  const onNavigateRef = useRef(onNavigate);\n  onNavigateRef.current = onNavigate;\n  const groupsRef = useRef(groups);\n  groupsRef.current = groups;\n\n  // Embedded: publish the tree whenever it changes. Serialising is the cheap\n  // way to dedupe — apps build `groups` inline every render.\n  const payload = embedded\n    ? JSON.stringify({ title, icon, groups: sanitize(groups), active })\n    : \"\";\n  const lastSent = useRef(\"\");\n  useEffect(() => {\n    if (!embedded || payload === lastSent.current) return;\n    lastSent.current = payload;\n    const { title, icon, groups, active } = JSON.parse(payload) as {\n      title: string;\n      icon?: string;\n      groups: AppNavGroup[];\n      active?: string;\n    };\n    post({ source: \"clawnify-app\", v: HOST_BRIDGE_VERSION, type: \"nav\", title, icon, groups, active });\n  }, [payload]);\n\n  // Embedded: handshake + listen for the host's clicks.\n  useEffect(() => {\n    if (!embedded) return;\n    function onMessage(e: MessageEvent) {\n      if (e.source !== window.parent) return;\n      const d = e.data as HostToAppMessage | undefined;\n      if (!d || d.source !== \"clawnify-host\" || d.v !== HOST_BRIDGE_VERSION) return;\n      if (d.type === \"hello\") {\n        // Host (re)mounted its listener after we first published: resend.\n        lastSent.current = \"\";\n        const g = sanitize(groupsRef.current);\n        post({ source: \"clawnify-app\", v: HOST_BRIDGE_VERSION, type: \"nav\", title, icon, groups: g, active });\n      } else if (d.type === \"navigate\" && typeof d.id === \"string\") {\n        const item = groupsRef.current.flatMap((g) => g.items).find((i) => i.id === d.id);\n        if (item) onNavigateRef.current(item);\n      }\n    }\n    window.addEventListener(\"message\", onMessage);\n    post({ source: \"clawnify-app\", v: HOST_BRIDGE_VERSION, type: \"ready\" });\n    return () => window.removeEventListener(\"message\", onMessage);\n    // title/active are read from the closure only on `hello`; the publish\n    // effect above covers their normal updates.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  if (embedded) return null;\n\n  const home = groups.flatMap((g) => g.items).find((i) => i.home);\n  const brand = (\n    <>\n      {(() => { const I = iconFor(icon); return I ? <I size={16} aria-hidden /> : null; })()}\n      <span>{title}</span>\n    </>\n  );\n\n  return (\n    <aside className=\"cn-nav\">\n      <style>{CSS}</style>\n      {home ? (\n        <a\n          href={home.href ?? \"/\"}\n          className=\"cn-nav-brand\"\n          data-active={home.id === active || undefined}\n          aria-current={home.id === active ? \"page\" : undefined}\n          onClick={(e: MouseEvent) => {\n            if (e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0) return;\n            e.preventDefault();\n            onNavigate(home);\n          }}\n        >\n          {brand}\n        </a>\n      ) : (\n        <div className=\"cn-nav-brand\">{brand}</div>\n      )}\n      <nav className=\"cn-nav-groups\" aria-label=\"Primary\">\n        {groups.map((g, gi) => (\n          <div className=\"cn-nav-group\" key={g.label ?? gi}>\n            {g.label && <p className=\"cn-nav-eyebrow\">{g.label}</p>}\n            {g.items\n              .filter((item) => !item.home)\n              .map((item) => (\n                <NavRow key={item.id} item={item} active={item.id === active} onNavigate={onNavigate} />\n              ))}\n          </div>\n        ))}\n      </nav>\n      {children && <div className=\"cn-nav-footer\">{children}</div>}\n    </aside>\n  );\n}\n\nfunction NavRow({\n  item,\n  active,\n  onNavigate,\n}: {\n  item: AppNavItem;\n  active: boolean;\n  onNavigate: (item: AppNavItem) => void;\n}) {\n  const body = (\n    <>\n      <TileIcon icon={item.icon} color={item.color} seed={item.id} />\n      <span className=\"cn-nav-label\">{item.label}</span>\n      {typeof item.count === \"number\" && <span className=\"cn-nav-count\">{item.count}</span>}\n    </>\n  );\n  // A real link when there is an href — middle-click and copy-link keep\n  // working — but the click itself goes through the app's router.\n  if (item.href) {\n    return (\n      <a\n        href={item.href}\n        className=\"cn-nav-item\"\n        data-active={active || undefined}\n        aria-current={active ? \"page\" : undefined}\n        onClick={(e: MouseEvent) => {\n          if (e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0) return;\n          e.preventDefault();\n          onNavigate(item);\n        }}\n      >\n        {body}\n      </a>\n    );\n  }\n  return (\n    <button\n      type=\"button\"\n      className=\"cn-nav-item\"\n      data-active={active || undefined}\n      aria-current={active ? \"page\" : undefined}\n      onClick={() => onNavigate(item)}\n    >\n      {body}\n    </button>\n  );\n}\n\n/** Our names → Phosphor components; the same map the dashboard holds. */\nconst ICONS: Record<string, PhosphorIcon> = {\n  \"activity\": Pulse,\n  \"archive\": Archive,\n  \"bar-chart-3\": ChartBar,\n  \"bell\": Bell,\n  \"book-open\": BookOpen,\n  \"bot\": Robot,\n  \"briefcase\": Briefcase,\n  \"building-2\": Building,\n  \"calendar\": Calendar,\n  \"calendar-days\": CalendarDots,\n  \"camera\": Camera,\n  \"check-square\": CheckSquare,\n  \"clipboard-list\": ClipboardText,\n  \"clock\": Clock,\n  \"code-2\": Code,\n  \"contact\": AddressBook,\n  \"credit-card\": CreditCard,\n  \"database\": Database,\n  \"dollar-sign\": CurrencyDollar,\n  \"file\": File,\n  \"file-text\": FileText,\n  \"folder\": Folder,\n  \"globe\": Globe,\n  \"hash\": Hash,\n  \"history\": ClockCounterClockwise,\n  \"home\": House,\n  \"image\": Image,\n  \"inbox\": Tray,\n  \"kanban\": Kanban,\n  \"layers\": Stack,\n  \"layout-dashboard\": SquaresFour,\n  \"layout-grid\": GridFour,\n  \"link\": Link,\n  \"list\": List,\n  \"list-checks\": ListChecks,\n  \"mail\": Envelope,\n  \"map\": MapTrifold,\n  \"message-square\": ChatCircle,\n  \"mic\": Microphone,\n  \"package\": Package,\n  \"phone\": Phone,\n  \"pie-chart\": ChartPie,\n  \"play\": Play,\n  \"search\": MagnifyingGlass,\n  \"send\": PaperPlaneTilt,\n  \"settings\": Gear,\n  \"shopping-cart\": ShoppingCart,\n  \"sparkles\": Sparkle,\n  \"star\": Star,\n  \"table\": Table,\n  \"tag\": Tag,\n  \"target\": Target,\n  \"truck\": Truck,\n  \"upload\": Upload,\n  \"user\": User,\n  \"users\": User,\n  \"video\": VideoCamera,\n  \"wallet\": Wallet,\n  \"zap\": Lightning,\n};\nfunction iconFor(name?: string): PhosphorIcon | undefined {\n  return name ? ICONS[name] : undefined;\n}\n\n/** Only the fields the protocol defines, with sane bounds, cross the bridge. */\nfunction sanitize(groups: AppNavGroup[]): AppNavGroup[] {\n  return groups.slice(0, 20).map((g) => ({\n    ...(g.label ? { label: String(g.label).slice(0, 40) } : {}),\n    items: g.items.slice(0, 100).map((i) => ({\n      id: String(i.id),\n      label: String(i.label).slice(0, 60),\n      ...(i.href ? { href: String(i.href) } : {}),\n      ...(i.icon ? { icon: String(i.icon) } : {}),\n      ...(typeof i.count === \"number\" && Number.isFinite(i.count) ? { count: i.count } : {}),\n      ...(i.home ? { home: true } : {}),\n      ...(i.color && i.color in NAV_COLORS ? { color: i.color } : {}),\n    })),\n  }));\n}\n\n// Scoped by class prefix; tokens follow apps/DESIGN.md with its light defaults\n// as fallbacks, so an app with a partial theme still gets a readable sidebar.\nconst CSS = `\n.cn-nav{width:16.25rem;flex-shrink:0;display:flex;flex-direction:column;border-right:1px solid var(--border,#e2e8f0);background:var(--surface,#fff);color:var(--foreground,#1a202c)}\n.cn-nav-brand{height:3.5rem;flex-shrink:0;display:flex;align-items:center;gap:.5rem;padding:0 1.25rem;border-bottom:1px solid var(--border,#e2e8f0);font-size:.875rem;font-weight:600;color:inherit;text-decoration:none}\na.cn-nav-brand:hover{background:var(--sunken,#f1f5f9)}\n.cn-nav-brand>svg{color:var(--primary,#dd5164)}\n.cn-nav-groups{flex:1;overflow-y:auto;padding:.75rem}\n.cn-nav-group+.cn-nav-group{margin-top:1rem}\n.cn-nav-eyebrow{margin:0 0 .25rem;padding:0 .625rem;font-size:.75rem;font-weight:500;color:var(--muted,#475569)}\n.cn-nav-item{display:flex;align-items:center;gap:.5rem;width:100%;margin:0 0 .125rem;padding:.4375rem .625rem;border:0;border-radius:.375rem;background:none;color:inherit;font:inherit;font-size:.875rem;text-align:left;text-decoration:none;cursor:pointer}\n.cn-nav-item:hover{background:var(--sunken,#f1f5f9)}\n.cn-nav-item[data-active]{background:color-mix(in srgb,var(--primary,#dd5164) 12%,transparent);color:var(--primary,#dd5164);font-weight:600}\n.cn-nav-item:focus-visible{outline:2px solid var(--ring,#2563eb);outline-offset:-2px}\n.cn-nav-label{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}\n.cn-nav-count{font-size:.75rem;font-variant-numeric:tabular-nums;color:var(--muted,#475569)}\n.cn-nav-item[data-active] .cn-nav-count{color:inherit}\n.cn-nav-footer{padding:.75rem;border-top:1px solid var(--border,#e2e8f0)}\n@media (max-width:767px){\n.cn-nav{width:100%;flex-direction:row;border-right:0;border-bottom:1px solid var(--border,#e2e8f0)}\n.cn-nav-brand,.cn-nav-eyebrow,.cn-nav-footer{display:none}\n.cn-nav-groups{display:flex;gap:.25rem;padding:.5rem .75rem;overflow-x:auto;overflow-y:hidden}\n.cn-nav-group{display:flex;gap:.25rem}\n.cn-nav-group+.cn-nav-group{margin:0}\n.cn-nav-item{width:auto;margin:0;white-space:nowrap}\n}\n`;\n"],"mappings":"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","names":["title","icon","groups","active"]}

package/dist/index.d.ts

@@ -46,7 +46,7 @@ interface RequestLike {
  * | `public`        | an unauthenticated visitor on a declared public route       |
  * | `bypass`        | platform-internal fetch (build/screenshot)                  |
  * | `system`        | the build pipeline                                          |
- * | `app`           | another app in the same org                                 |
+ * | `app`           | another app in the same org (or a headless org-token caller)|
  */
 type Caller = "user" | "api" | "agent" | "agent-browser" | "public" | "bypass" | "system" | "app";
 /** The signed-in person behind a request. */

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/identity.ts"],"sourcesContent":["/**\n * @clawnify/app — the standard Clawnify app skeleton in one call.\n *\n * `createApp(opts)` returns a fully-wired OpenAPIHono with every always-required,\n * cross-cutting concern pre-baked, so an app's server file is just imports +\n * routes + `export default app`:\n *\n *   import { createApp, createRoute, z } from \"@clawnify/app\";\n *   const app = createApp<Env>({ title: \"CRM App\", version: \"1.0.0\" });\n *   app.openapi(listContacts, handler);\n *   export default app;\n *\n * What it bakes in — the boilerplate every app used to re-write in its server\n * file, and could forget:\n *   • OpenAPIHono construction (typed to your Env).\n *   • Database init — `initDB(c.env)` middleware on every request. @clawnify/db\n *     auto-detects the D1 binding (production WfP) or the Storage capability\n *     binding (Dynamic Workers preview), so handlers can query immediately.\n *   • API discovery — `mountDiscovery` serves GET /api/openapi.json (the machine\n *     contract) and GET /llms.txt (the lean agent index), generated from the\n *     live routes so they can't drift.\n *   • Identity — `user(c)` / `orgId(c)` / `caller(c)` read the platform-injected\n *     `X-Clawnify-*` headers, so an app never hand-parses them (see identity.ts).\n *\n * The point: a new always-required concern is added HERE once and every app\n * inherits it on the next rebuild — instead of a line each agent must remember\n * to write (and a build gate to enforce) in every app.\n */\nimport { OpenAPIHono, mountDiscovery, type DiscoveryOptions } from \"@clawnify/routes\";\nimport { initDB } from \"@clawnify/db\";\nimport type { Env } from \"hono\";\n\n// One routing import for app authors: everything needed to declare routes and\n// build the app comes from @clawnify/app. These are re-exports of the same\n// @hono/zod-openapi primitives @clawnify/routes exposes — never reimplemented —\n// so route creation, discovery, and construction all live behind one import.\nexport {\n  OpenAPIHono,\n  createRoute,\n  z,\n  mountDiscovery,\n  describeRoutes,\n} from \"@clawnify/routes\";\nexport type { DiscoveryOptions, DiscoverableApp } from \"@clawnify/routes\";\n\n// Identity of the caller, read from the platform-injected headers. Apps never\n// authenticate anyone themselves — see identity.ts.\nexport { user, orgId, caller } from \"./identity\";\nexport type { AppUser, Caller, RequestLike } from \"./identity\";\n\nexport interface CreateAppOptions extends DiscoveryOptions {\n  /**\n   * Wire the per-request database middleware (`initDB(c.env)` on `*`). Default\n   * true — every Clawnify app has a D1 / Storage binding. Set false only for the\n   * rare app with no database.\n   */\n  db?: boolean;\n  /**\n   * Mount GET /api/openapi.json + GET /llms.txt discovery. Default true. Set\n   * false only if the app deliberately opts out of API discovery.\n   */\n  discovery?: boolean;\n}\n\n/**\n * Create a fully-wired Clawnify app.\n *\n * `E` is your Hono env — `{ Bindings: { DB: D1Database, ... } }` — pass it so\n * route handlers get a typed `c.env`. Everything after this call is your app's\n * own routes and business logic:\n *\n *   const app = createApp<Env>({ title: \"CRM App\", version: \"1.0.0\" });\n *   app.openapi(route, handler);\n *   export default app;\n */\nexport function createApp<E extends Env = Env>(\n  opts: CreateAppOptions = {},\n): OpenAPIHono<E> {\n  const app = new OpenAPIHono<E>();\n\n  if (opts.db !== false) {\n    app.use(\"*\", async (c, next) => {\n      // @clawnify/db reads the DB (D1) or Storage binding off the env and caches\n      // the Drizzle client for this request. Safe to call on every request.\n      initDB(c.env as unknown as Parameters<typeof initDB>[0]);\n      await next();\n    });\n  }\n\n  if (opts.discovery !== false) {\n    mountDiscovery(app, opts);\n  }\n\n  return app;\n}\n","/**\n * Identity — who is calling this app.\n *\n * The platform authenticates the caller at the perimeter (app-router, the\n * app-supervisor preview tier, or the /v1/apps/:id/proxy API) and injects a\n * *fresh* set of `X-Clawnify-*` headers. Any client-supplied `X-Clawnify-*` is\n * stripped first, so these headers cannot be spoofed and an app can trust them\n * directly.\n *\n * Apps therefore never authenticate anyone themselves: never read\n * `Authorization`, never parse a cookie, never verify a JWT. Read these\n * helpers instead.\n *\n *   import { user, orgId, caller } from \"@clawnify/app\";\n *\n *   app.openapi(route, (c) => {\n *     const u = user(c);                       // null when the caller isn't a person\n *     return c.json({ hello: u?.name ?? \"there\", org: orgId(c) });\n *   });\n */\n\n/**\n * Minimal shape this module needs — Hono's `Context` satisfies it structurally,\n * so `user(c)` works in any handler regardless of the app's Env generics.\n */\nexport interface RequestLike {\n  req: { header(name: string): string | undefined };\n}\n\n/**\n * What kind of principal is calling.\n *\n * Only `user`, `api` and `agent` carry a human identity; the rest are machine\n * or anonymous callers, for which `user()` returns null.\n *\n * | Value           | Who                                                        |\n * |-----------------|------------------------------------------------------------|\n * | `user`          | a signed-in person in a browser                             |\n * | `api`           | a person via the REST API / CLI / MCP (their own token)     |\n * | `agent`         | the org's OpenClaw agent calling the app's API              |\n * | `agent-browser` | the agent driving a real browser on its VPS                 |\n * | `public`        | an unauthenticated visitor on a declared public route       |\n * | `bypass`        | platform-internal fetch (build/screenshot)                  |\n * | `system`        | the build pipeline                                          |\n * | `app`           | another app in the same org                                 |\n */\nexport type Caller =\n  | \"user\"\n  | \"api\"\n  | \"agent\"\n  | \"agent-browser\"\n  | \"public\"\n  | \"bypass\"\n  | \"system\"\n  | \"app\";\n\nconst CALLERS = new Set<Caller>([\n  \"user\",\n  \"api\",\n  \"agent\",\n  \"agent-browser\",\n  \"public\",\n  \"bypass\",\n  \"system\",\n  \"app\",\n]);\n\n/** The signed-in person behind a request. */\nexport interface AppUser {\n  /** Supabase user id — the stable key to store on rows (`created_by`). */\n  id: string;\n  email: string | null;\n  /** Display name, e.g. \"Ada Lovelace\". Null if the account has no name set. */\n  name: string | null;\n  /** Profile picture URL (https). Null if the account has no avatar. */\n  avatarUrl: string | null;\n  /**\n   * Best-effort split of `name` — a HEURISTIC, not platform data.\n   *\n   * The platform stores one `full_name`; there is no real given/family split\n   * behind it. This takes the first whitespace-separated token, which is wrong\n   * for many names (mononyms, multi-word given names, family-name-first\n   * cultures). Use it for a friendly greeting (\"Hi, Ada\"), never as a stored\n   * field or a record of someone's legal name — persist `name` instead.\n   */\n  firstName: string | null;\n  /** Remainder of `name` after the first token. Same heuristic caveat. */\n  lastName: string | null;\n}\n\nfunction read(c: RequestLike, name: string): string | null {\n  const v = c.req.header(name);\n  if (v === undefined) return null;\n  const trimmed = v.trim();\n  return trimmed === \"\" ? null : trimmed;\n}\n\nfunction splitName(name: string | null): Pick<AppUser, \"firstName\" | \"lastName\"> {\n  if (!name) return { firstName: null, lastName: null };\n  const parts = name.split(/\\s+/).filter(Boolean);\n  if (parts.length === 0) return { firstName: null, lastName: null };\n  if (parts.length === 1) return { firstName: parts[0], lastName: null };\n  return { firstName: parts[0], lastName: parts.slice(1).join(\" \") };\n}\n\n/**\n * What kind of principal is calling.\n *\n * Defaults to `\"public\"` — the least-privileged value — when the header is\n * missing or unrecognised, which happens when the app is reached outside the\n * platform perimeter (local `pnpm dev`). Gate privileged behaviour on an\n * explicit check (`caller(c) === \"user\"`), never on \"not public\".\n */\nexport function caller(c: RequestLike): Caller {\n  const v = read(c, \"X-Clawnify-Caller\");\n  return v && CALLERS.has(v as Caller) ? (v as Caller) : \"public\";\n}\n\n/**\n * The organization this request belongs to — the tenant key. Scope every query\n * by it.\n *\n * Present for `user`, `api`, `agent` and `app` callers. **Null** for\n * `agent-browser`, `public` and `bypass` — those reach the app through the\n * perimeter without an org-scoped identity — and null outside the platform.\n *\n * Treat null as \"no access\", never as a wildcard: a query filtered on a null\n * org must return nothing, not everything.\n */\nexport function orgId(c: RequestLike): string | null {\n  return read(c, \"X-Clawnify-Org-Id\");\n}\n\n/**\n * The person behind this request, or `null` when the caller isn't one.\n *\n * Null for `agent-browser`, `public`, `bypass`, `system` and `app` — five of\n * the eight caller types — so always handle the null case rather than assuming\n * a user is present:\n *\n *   const u = user(c);\n *   const label = u ? u.name ?? u.email : \"Automated\";\n */\nexport function user(c: RequestLike): AppUser | null {\n  const id = read(c, \"X-Clawnify-User-Id\");\n  if (!id) return null;\n\n  const name = read(c, \"X-Clawnify-User-Name\");\n  return {\n    id,\n    email: read(c, \"X-Clawnify-User-Email\"),\n    name,\n    avatarUrl: read(c, \"X-Clawnify-User-Avatar\"),\n    ...splitName(name),\n  };\n}\n"],"mappings":";AA4BA,SAAS,aAAa,sBAA6C;AACnE,SAAS,cAAc;AAOvB;AAAA,EACE,eAAAA;AAAA,EACA;AAAA,EACA;AAAA,EACA,kBAAAC;AAAA,EACA;AAAA,OACK;;;ACcP,IAAM,UAAU,oBAAI,IAAY;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAyBD,SAAS,KAAK,GAAgB,MAA6B;AACzD,QAAM,IAAI,EAAE,IAAI,OAAO,IAAI;AAC3B,MAAI,MAAM,OAAW,QAAO;AAC5B,QAAM,UAAU,EAAE,KAAK;AACvB,SAAO,YAAY,KAAK,OAAO;AACjC;AAEA,SAAS,UAAU,MAA8D;AAC/E,MAAI,CAAC,KAAM,QAAO,EAAE,WAAW,MAAM,UAAU,KAAK;AACpD,QAAM,QAAQ,KAAK,MAAM,KAAK,EAAE,OAAO,OAAO;AAC9C,MAAI,MAAM,WAAW,EAAG,QAAO,EAAE,WAAW,MAAM,UAAU,KAAK;AACjE,MAAI,MAAM,WAAW,EAAG,QAAO,EAAE,WAAW,MAAM,CAAC,GAAG,UAAU,KAAK;AACrE,SAAO,EAAE,WAAW,MAAM,CAAC,GAAG,UAAU,MAAM,MAAM,CAAC,EAAE,KAAK,GAAG,EAAE;AACnE;AAUO,SAAS,OAAO,GAAwB;AAC7C,QAAM,IAAI,KAAK,GAAG,mBAAmB;AACrC,SAAO,KAAK,QAAQ,IAAI,CAAW,IAAK,IAAe;AACzD;AAaO,SAAS,MAAM,GAA+B;AACnD,SAAO,KAAK,GAAG,mBAAmB;AACpC;AAYO,SAAS,KAAK,GAAgC;AACnD,QAAM,KAAK,KAAK,GAAG,oBAAoB;AACvC,MAAI,CAAC,GAAI,QAAO;AAEhB,QAAM,OAAO,KAAK,GAAG,sBAAsB;AAC3C,SAAO;AAAA,IACL;AAAA,IACA,OAAO,KAAK,GAAG,uBAAuB;AAAA,IACtC;AAAA,IACA,WAAW,KAAK,GAAG,wBAAwB;AAAA,IAC3C,GAAG,UAAU,IAAI;AAAA,EACnB;AACF;;;ADhFO,SAAS,UACd,OAAyB,CAAC,GACV;AAChB,QAAM,MAAM,IAAI,YAAe;AAE/B,MAAI,KAAK,OAAO,OAAO;AACrB,QAAI,IAAI,KAAK,OAAO,GAAG,SAAS;AAG9B,aAAO,EAAE,GAA8C;AACvD,YAAM,KAAK;AAAA,IACb,CAAC;AAAA,EACH;AAEA,MAAI,KAAK,cAAc,OAAO;AAC5B,mBAAe,KAAK,IAAI;AAAA,EAC1B;AAEA,SAAO;AACT;","names":["OpenAPIHono","mountDiscovery"]}
+{"version":3,"sources":["../src/index.ts","../src/identity.ts"],"sourcesContent":["/**\n * @clawnify/app — the standard Clawnify app skeleton in one call.\n *\n * `createApp(opts)` returns a fully-wired OpenAPIHono with every always-required,\n * cross-cutting concern pre-baked, so an app's server file is just imports +\n * routes + `export default app`:\n *\n *   import { createApp, createRoute, z } from \"@clawnify/app\";\n *   const app = createApp<Env>({ title: \"CRM App\", version: \"1.0.0\" });\n *   app.openapi(listContacts, handler);\n *   export default app;\n *\n * What it bakes in — the boilerplate every app used to re-write in its server\n * file, and could forget:\n *   • OpenAPIHono construction (typed to your Env).\n *   • Database init — `initDB(c.env)` middleware on every request. @clawnify/db\n *     auto-detects the D1 binding (production WfP) or the Storage capability\n *     binding (Dynamic Workers preview), so handlers can query immediately.\n *   • API discovery — `mountDiscovery` serves GET /api/openapi.json (the machine\n *     contract) and GET /llms.txt (the lean agent index), generated from the\n *     live routes so they can't drift.\n *   • Identity — `user(c)` / `orgId(c)` / `caller(c)` read the platform-injected\n *     `X-Clawnify-*` headers, so an app never hand-parses them (see identity.ts).\n *\n * The point: a new always-required concern is added HERE once and every app\n * inherits it on the next rebuild — instead of a line each agent must remember\n * to write (and a build gate to enforce) in every app.\n */\nimport { OpenAPIHono, mountDiscovery, type DiscoveryOptions } from \"@clawnify/routes\";\nimport { initDB } from \"@clawnify/db\";\nimport type { Env } from \"hono\";\n\n// One routing import for app authors: everything needed to declare routes and\n// build the app comes from @clawnify/app. These are re-exports of the same\n// @hono/zod-openapi primitives @clawnify/routes exposes — never reimplemented —\n// so route creation, discovery, and construction all live behind one import.\nexport {\n  OpenAPIHono,\n  createRoute,\n  z,\n  mountDiscovery,\n  describeRoutes,\n} from \"@clawnify/routes\";\nexport type { DiscoveryOptions, DiscoverableApp } from \"@clawnify/routes\";\n\n// Identity of the caller, read from the platform-injected headers. Apps never\n// authenticate anyone themselves — see identity.ts.\nexport { user, orgId, caller } from \"./identity\";\nexport type { AppUser, Caller, RequestLike } from \"./identity\";\n\nexport interface CreateAppOptions extends DiscoveryOptions {\n  /**\n   * Wire the per-request database middleware (`initDB(c.env)` on `*`). Default\n   * true — every Clawnify app has a D1 / Storage binding. Set false only for the\n   * rare app with no database.\n   */\n  db?: boolean;\n  /**\n   * Mount GET /api/openapi.json + GET /llms.txt discovery. Default true. Set\n   * false only if the app deliberately opts out of API discovery.\n   */\n  discovery?: boolean;\n}\n\n/**\n * Create a fully-wired Clawnify app.\n *\n * `E` is your Hono env — `{ Bindings: { DB: D1Database, ... } }` — pass it so\n * route handlers get a typed `c.env`. Everything after this call is your app's\n * own routes and business logic:\n *\n *   const app = createApp<Env>({ title: \"CRM App\", version: \"1.0.0\" });\n *   app.openapi(route, handler);\n *   export default app;\n */\nexport function createApp<E extends Env = Env>(\n  opts: CreateAppOptions = {},\n): OpenAPIHono<E> {\n  const app = new OpenAPIHono<E>();\n\n  if (opts.db !== false) {\n    app.use(\"*\", async (c, next) => {\n      // @clawnify/db reads the DB (D1) or Storage binding off the env and caches\n      // the Drizzle client for this request. Safe to call on every request.\n      initDB(c.env as unknown as Parameters<typeof initDB>[0]);\n      await next();\n    });\n  }\n\n  if (opts.discovery !== false) {\n    mountDiscovery(app, opts);\n  }\n\n  return app;\n}\n","/**\n * Identity — who is calling this app.\n *\n * The platform authenticates the caller at the perimeter (app-router, the\n * app-supervisor preview tier, or the /v1/apps/:id/proxy API) and injects a\n * *fresh* set of `X-Clawnify-*` headers. Any client-supplied `X-Clawnify-*` is\n * stripped first, so these headers cannot be spoofed and an app can trust them\n * directly.\n *\n * Apps therefore never authenticate anyone themselves: never read\n * `Authorization`, never parse a cookie, never verify a JWT. Read these\n * helpers instead.\n *\n *   import { user, orgId, caller } from \"@clawnify/app\";\n *\n *   app.openapi(route, (c) => {\n *     const u = user(c);                       // null when the caller isn't a person\n *     return c.json({ hello: u?.name ?? \"there\", org: orgId(c) });\n *   });\n */\n\n/**\n * Minimal shape this module needs — Hono's `Context` satisfies it structurally,\n * so `user(c)` works in any handler regardless of the app's Env generics.\n */\nexport interface RequestLike {\n  req: { header(name: string): string | undefined };\n}\n\n/**\n * What kind of principal is calling.\n *\n * Only `user`, `api` and `agent` carry a human identity; the rest are machine\n * or anonymous callers, for which `user()` returns null.\n *\n * | Value           | Who                                                        |\n * |-----------------|------------------------------------------------------------|\n * | `user`          | a signed-in person in a browser                             |\n * | `api`           | a person via the REST API / CLI / MCP (their own token)     |\n * | `agent`         | the org's OpenClaw agent calling the app's API              |\n * | `agent-browser` | the agent driving a real browser on its VPS                 |\n * | `public`        | an unauthenticated visitor on a declared public route       |\n * | `bypass`        | platform-internal fetch (build/screenshot)                  |\n * | `system`        | the build pipeline                                          |\n * | `app`           | another app in the same org (or a headless org-token caller)|\n */\nexport type Caller =\n  | \"user\"\n  | \"api\"\n  | \"agent\"\n  | \"agent-browser\"\n  | \"public\"\n  | \"bypass\"\n  | \"system\"\n  | \"app\";\n\nconst CALLERS = new Set<Caller>([\n  \"user\",\n  \"api\",\n  \"agent\",\n  \"agent-browser\",\n  \"public\",\n  \"bypass\",\n  \"system\",\n  \"app\",\n]);\n\n/** The signed-in person behind a request. */\nexport interface AppUser {\n  /** Supabase user id — the stable key to store on rows (`created_by`). */\n  id: string;\n  email: string | null;\n  /** Display name, e.g. \"Ada Lovelace\". Null if the account has no name set. */\n  name: string | null;\n  /** Profile picture URL (https). Null if the account has no avatar. */\n  avatarUrl: string | null;\n  /**\n   * Best-effort split of `name` — a HEURISTIC, not platform data.\n   *\n   * The platform stores one `full_name`; there is no real given/family split\n   * behind it. This takes the first whitespace-separated token, which is wrong\n   * for many names (mononyms, multi-word given names, family-name-first\n   * cultures). Use it for a friendly greeting (\"Hi, Ada\"), never as a stored\n   * field or a record of someone's legal name — persist `name` instead.\n   */\n  firstName: string | null;\n  /** Remainder of `name` after the first token. Same heuristic caveat. */\n  lastName: string | null;\n}\n\nfunction read(c: RequestLike, name: string): string | null {\n  const v = c.req.header(name);\n  if (v === undefined) return null;\n  const trimmed = v.trim();\n  return trimmed === \"\" ? null : trimmed;\n}\n\nfunction splitName(name: string | null): Pick<AppUser, \"firstName\" | \"lastName\"> {\n  if (!name) return { firstName: null, lastName: null };\n  const parts = name.split(/\\s+/).filter(Boolean);\n  if (parts.length === 0) return { firstName: null, lastName: null };\n  if (parts.length === 1) return { firstName: parts[0], lastName: null };\n  return { firstName: parts[0], lastName: parts.slice(1).join(\" \") };\n}\n\n/**\n * What kind of principal is calling.\n *\n * Defaults to `\"public\"` — the least-privileged value — when the header is\n * missing or unrecognised, which happens when the app is reached outside the\n * platform perimeter (local `pnpm dev`). Gate privileged behaviour on an\n * explicit check (`caller(c) === \"user\"`), never on \"not public\".\n */\nexport function caller(c: RequestLike): Caller {\n  const v = read(c, \"X-Clawnify-Caller\");\n  return v && CALLERS.has(v as Caller) ? (v as Caller) : \"public\";\n}\n\n/**\n * The organization this request belongs to — the tenant key. Scope every query\n * by it.\n *\n * Present for `user`, `api`, `agent` and `app` callers. **Null** for\n * `agent-browser`, `public` and `bypass` — those reach the app through the\n * perimeter without an org-scoped identity — and null outside the platform.\n *\n * Treat null as \"no access\", never as a wildcard: a query filtered on a null\n * org must return nothing, not everything.\n */\nexport function orgId(c: RequestLike): string | null {\n  return read(c, \"X-Clawnify-Org-Id\");\n}\n\n/**\n * The person behind this request, or `null` when the caller isn't one.\n *\n * Null for `agent-browser`, `public`, `bypass`, `system` and `app` — five of\n * the eight caller types — so always handle the null case rather than assuming\n * a user is present:\n *\n *   const u = user(c);\n *   const label = u ? u.name ?? u.email : \"Automated\";\n */\nexport function user(c: RequestLike): AppUser | null {\n  const id = read(c, \"X-Clawnify-User-Id\");\n  if (!id) return null;\n\n  const name = read(c, \"X-Clawnify-User-Name\");\n  return {\n    id,\n    email: read(c, \"X-Clawnify-User-Email\"),\n    name,\n    avatarUrl: read(c, \"X-Clawnify-User-Avatar\"),\n    ...splitName(name),\n  };\n}\n"],"mappings":";AA4BA,SAAS,aAAa,sBAA6C;AACnE,SAAS,cAAc;AAOvB;AAAA,EACE,eAAAA;AAAA,EACA;AAAA,EACA;AAAA,EACA,kBAAAC;AAAA,EACA;AAAA,OACK;;;ACcP,IAAM,UAAU,oBAAI,IAAY;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAyBD,SAAS,KAAK,GAAgB,MAA6B;AACzD,QAAM,IAAI,EAAE,IAAI,OAAO,IAAI;AAC3B,MAAI,MAAM,OAAW,QAAO;AAC5B,QAAM,UAAU,EAAE,KAAK;AACvB,SAAO,YAAY,KAAK,OAAO;AACjC;AAEA,SAAS,UAAU,MAA8D;AAC/E,MAAI,CAAC,KAAM,QAAO,EAAE,WAAW,MAAM,UAAU,KAAK;AACpD,QAAM,QAAQ,KAAK,MAAM,KAAK,EAAE,OAAO,OAAO;AAC9C,MAAI,MAAM,WAAW,EAAG,QAAO,EAAE,WAAW,MAAM,UAAU,KAAK;AACjE,MAAI,MAAM,WAAW,EAAG,QAAO,EAAE,WAAW,MAAM,CAAC,GAAG,UAAU,KAAK;AACrE,SAAO,EAAE,WAAW,MAAM,CAAC,GAAG,UAAU,MAAM,MAAM,CAAC,EAAE,KAAK,GAAG,EAAE;AACnE;AAUO,SAAS,OAAO,GAAwB;AAC7C,QAAM,IAAI,KAAK,GAAG,mBAAmB;AACrC,SAAO,KAAK,QAAQ,IAAI,CAAW,IAAK,IAAe;AACzD;AAaO,SAAS,MAAM,GAA+B;AACnD,SAAO,KAAK,GAAG,mBAAmB;AACpC;AAYO,SAAS,KAAK,GAAgC;AACnD,QAAM,KAAK,KAAK,GAAG,oBAAoB;AACvC,MAAI,CAAC,GAAI,QAAO;AAEhB,QAAM,OAAO,KAAK,GAAG,sBAAsB;AAC3C,SAAO;AAAA,IACL;AAAA,IACA,OAAO,KAAK,GAAG,uBAAuB;AAAA,IACtC;AAAA,IACA,WAAW,KAAK,GAAG,wBAAwB;AAAA,IAC3C,GAAG,UAAU,IAAI;AAAA,EACnB;AACF;;;ADhFO,SAAS,UACd,OAAyB,CAAC,GACV;AAChB,QAAM,MAAM,IAAI,YAAe;AAE/B,MAAI,KAAK,OAAO,OAAO;AACrB,QAAI,IAAI,KAAK,OAAO,GAAG,SAAS;AAG9B,aAAO,EAAE,GAA8C;AACvD,YAAM,KAAK;AAAA,IACb,CAAC;AAAA,EACH;AAEA,MAAI,KAAK,cAAc,OAAO;AAC5B,mBAAe,KAAK,IAAI;AAAA,EAC1B;AAEA,SAAO;AACT;","names":["OpenAPIHono","mountDiscovery"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawnify/app",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "The standard Clawnify app skeleton in one call. createApp() returns a fully-wired OpenAPIHono with D1/Storage init + /api/openapi.json + /llms.txt discovery pre-baked, so an app is just imports + routes + export.",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,26 +12,45 @@
       "import": "./dist/index.js",
       "require": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js",
+      "default": "./dist/client/index.js"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@clawnify/routes": "^0.2.1",
-    "@clawnify/db": "^0.4.1"
+    "@clawnify/db": "^0.4.1",
+    "@clawnify/routes": "^0.2.2"
   },
   "peerDependencies": {
     "@hono/zod-openapi": ">=0.18 <1",
-    "hono": "*"
+    "hono": "*",
+    "react": ">=18",
+    "@phosphor-icons/react": ">=2"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260405.1",
     "@hono/zod-openapi": "^0.18.0",
+    "@phosphor-icons/react": "^2.1.10",
+    "@types/react": "^19.0.0",
     "hono": "^4.6.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "tsup": "^8.0.0",
     "typescript": "^5.7.0"
   },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@phosphor-icons/react": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch"