@tribe-nest/forge 3.19.0 → 3.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.19.0",
+  "version": "3.20.0",
   "publishConfig": {
     "access": "public"
   },

package/src/ui/shell/TribeNestApp.tsx

@@ -5,11 +5,12 @@ import { ForgeAnalytics } from "../analytics/ForgeAnalytics";
 import { PwaRegistration } from "../styled/PwaRegistration";
 import { InstallBanner } from "../styled/InstallBanner";
 import { CookieConsent } from "../styled/CookieConsent";
+import { AiAgentWidget } from "../styled/AiAgentWidget";
 import { useThemeTokens } from "../theme/ForgeThemeProvider";
 import { useInitialSiteConfig } from "../../provider/SiteConfigProvider";
 import { PoweredBy } from "./PoweredBy";
 import { PreviewDiagnostics } from "./PreviewDiagnostics";
-import { shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
+import { shellAiAgentEnabled, shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
 import { previewDiagnosticsEnabled, resolvePreviewDiagnostics } from "./diagnosticsGating";
 import type { ForgeSsrDiagnostics } from "../../types/diagnostics";
 import { captureAttributionRefFromUrl, readAttributionRef } from "../../utils/attribution";
@@ -52,6 +53,14 @@ export interface TribeNestAppProps extends Omit<ForgeProviderProps, "children">
   analytics?: boolean;
   pwa?: boolean;
   cookieConsent?: boolean;
+  /**
+   * The website AI agent bubble. Defaults to on for a fan site and off for a
+   * mini-app; set it explicitly to override either default. Renders nothing
+   * unless the creator has also enabled the agent for the profile — the widget
+   * fetches its own config and self-hides. For custom chat UI, leave this off
+   * and build on the `useAiAgent()` hook instead.
+   */
+  aiAgent?: boolean;
 }
 
 // Ensure the PWA `<link rel="manifest">` + a `theme-color` meta exist even if the
@@ -114,6 +123,7 @@ export function TribeNestApp({
   analytics = true,
   pwa = true,
   cookieConsent = true,
+  aiAgent,
   ...forgeProps
 }: TribeNestAppProps) {
   // Register the SW + offer install only on the live published site — never in
@@ -154,6 +164,11 @@ export function TribeNestApp({
       {/* Consent banner — shown on first visit, re-openable from anywhere via
           useCookieConsent().reopen(). Hidden in the editor. */}
       {cookieConsent && !editable && <CookieConsent useTribeNestPrivacy />}
+      {/* Website AI agent — floating bubble, self-hiding when the profile has no
+          agent enabled. Lives here rather than in each __root so enabling the
+          agent in admin is enough to make it appear; before this it shipped only
+          on the Craft stack and no code site ever rendered it. */}
+      {shellAiAgentEnabled({ aiAgent, editable, appId: forgeProps.appId }) && <AiAgentWidget />}
     </ForgeProvider>
   );
 }

package/src/ui/shell/shellGating.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { poweredByHref, shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
+import { poweredByHref, shellAiAgentEnabled, shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
 
 // The PWA (SW register + install prompt) must be ON only for the live published
 // site, and OFF everywhere else (editor, preview/draft), so review Workers never
@@ -47,6 +47,31 @@ describe("shellPoweredByEnabled", () => {
   });
 });
 
+// The agent bubble defaults ON for fan sites and OFF for mini-apps, and is
+// blocked in the editor because an answer there spends the creator's AI credits.
+// The widget itself still renders nothing when the agent is disabled for the
+// profile — this gate is about the SURFACE, not the entitlement.
+describe("shellAiAgentEnabled", () => {
+  it("is on by default for a fan site, live or preview", () => {
+    expect(shellAiAgentEnabled({ editable: false })).toBe(true);
+    expect(shellAiAgentEnabled({})).toBe(true);
+  });
+
+  it("is off by default for a mini-app", () => {
+    expect(shellAiAgentEnabled({ editable: false, appId: "app-7" })).toBe(false);
+  });
+
+  it("is off in the editor even when explicitly asked for", () => {
+    expect(shellAiAgentEnabled({ aiAgent: true, editable: true })).toBe(false);
+    expect(shellAiAgentEnabled({ editable: true })).toBe(false);
+  });
+
+  it("lets an explicit prop override the per-surface default in both directions", () => {
+    expect(shellAiAgentEnabled({ aiAgent: false, editable: false })).toBe(false); // site opts out
+    expect(shellAiAgentEnabled({ aiAgent: true, editable: false, appId: "app-7" })).toBe(true); // app opts in
+  });
+});
+
 // The badge is only worth carrying if we can tell WHICH site sent the visitor,
 // so the identifying params are the point of the link, not decoration.
 describe("poweredByHref", () => {

package/src/ui/shell/shellGating.ts

@@ -24,6 +24,22 @@ export function shellPoweredByEnabled(opts: {
   return !opts.hideBadge && !opts.editable && opts.state === "published";
 }
 
+// The website AI agent bubble. Unlike the PWA it IS wanted on preview/draft
+// deploys — that is where a creator checks the assistant before going live — so
+// the only hard block is the HMR editor, where a live answer would spend the
+// creator's AI credits every time they typed into their own site.
+//
+// The default differs by surface. A fan site gets it (the agent answers from the
+// artist's content + knowledge base, which is what a visitor is there for); a
+// mini-app does NOT, because an app is a utility and a floating "ask me about
+// the artist" bubble is noise on top of it. `appId` is baked at build time, so
+// this is decided without a runtime lookup. An explicit `aiAgent` prop wins
+// either way — that is how an app opts in, or a site opts out.
+export function shellAiAgentEnabled(opts: { aiAgent?: boolean; editable?: boolean; appId?: string }): boolean {
+  if (opts.editable) return false;
+  return opts.aiAgent ?? !opts.appId;
+}
+
 /** Marketing site the badge points at. */
 const TRIBENEST_URL = "https://tribenest.co/";