@carlonicora/nextjs-jsonapi 2.0.3 → 2.1.0

package/dist/server/index.js

@@ -15,7 +15,7 @@ var _chunkIOLU4ASDjs = require('../chunk-IOLU4ASD.js');
 
 
 
-var _chunkDS4IBFWAjs = require('../chunk-DS4IBFWA.js');
+var _chunk6YIZX26Tjs = require('../chunk-6YIZX26T.js');
 require('../chunk-LXKSUWAV.js');
 require('../chunk-IBS6NI7D.js');
 
@@ -86,7 +86,7 @@ var ServerSession = class {
     if (!rawModules) return false;
     const modules = JSON.parse(_pako.ungzip.call(void 0, Buffer.from(rawModules, "base64"), { toText: true }));
     const selectedModule = modules.find((module) => module.id === params.module.moduleId);
-    return _chunkDS4IBFWAjs.checkPermissionsFromServer.call(void 0, {
+    return _chunk6YIZX26Tjs.checkPermissionsFromServer.call(void 0, {
       module: params.module,
       action: params.action,
       data: params.data,
@@ -296,5 +296,5 @@ _chunk7QVYU63Ejs.__name.call(void 0, ServerJsonApiDelete, "ServerJsonApiDelete")
 
 
 
-exports.ServerAuthService = _chunkDS4IBFWAjs.AuthService; exports.ServerCompanyService = _chunkDS4IBFWAjs.CompanyService; exports.ServerContentService = _chunkDS4IBFWAjs.ContentService; exports.ServerFeatureService = _chunkDS4IBFWAjs.FeatureService; exports.ServerJsonApiDelete = ServerJsonApiDelete; exports.ServerJsonApiGet = ServerJsonApiGet; exports.ServerJsonApiPatch = ServerJsonApiPatch; exports.ServerJsonApiPost = ServerJsonApiPost; exports.ServerJsonApiPut = ServerJsonApiPut; exports.ServerNotificationService = _chunkDS4IBFWAjs.NotificationService; exports.ServerPushService = _chunkDS4IBFWAjs.PushService; exports.ServerRoleService = _chunkDS4IBFWAjs.RoleService; exports.ServerS3Service = _chunkDS4IBFWAjs.S3Service; exports.ServerSession = ServerSession; exports.ServerUserService = _chunkDS4IBFWAjs.UserService; exports.configureServerJsonApi = configureServerJsonApi; exports.getServerApiUrl = getServerApiUrl; exports.getServerAppUrl = getServerAppUrl; exports.getServerToken = _chunkYUO55Q5Ajs.getServerToken; exports.getServerTrackablePages = getServerTrackablePages; exports.invalidateCacheTag = invalidateCacheTag; exports.invalidateCacheTags = invalidateCacheTags; exports.serverRequest = _chunkIOLU4ASDjs.serverRequest;
+exports.ServerAuthService = _chunk6YIZX26Tjs.AuthService; exports.ServerCompanyService = _chunk6YIZX26Tjs.CompanyService; exports.ServerContentService = _chunk6YIZX26Tjs.ContentService; exports.ServerFeatureService = _chunk6YIZX26Tjs.FeatureService; exports.ServerJsonApiDelete = ServerJsonApiDelete; exports.ServerJsonApiGet = ServerJsonApiGet; exports.ServerJsonApiPatch = ServerJsonApiPatch; exports.ServerJsonApiPost = ServerJsonApiPost; exports.ServerJsonApiPut = ServerJsonApiPut; exports.ServerNotificationService = _chunk6YIZX26Tjs.NotificationService; exports.ServerPushService = _chunk6YIZX26Tjs.PushService; exports.ServerRoleService = _chunk6YIZX26Tjs.RoleService; exports.ServerS3Service = _chunk6YIZX26Tjs.S3Service; exports.ServerSession = ServerSession; exports.ServerUserService = _chunk6YIZX26Tjs.UserService; exports.configureServerJsonApi = configureServerJsonApi; exports.getServerApiUrl = getServerApiUrl; exports.getServerAppUrl = getServerAppUrl; exports.getServerToken = _chunkYUO55Q5Ajs.getServerToken; exports.getServerTrackablePages = getServerTrackablePages; exports.invalidateCacheTag = invalidateCacheTag; exports.invalidateCacheTags = invalidateCacheTags; exports.serverRequest = _chunkIOLU4ASDjs.serverRequest;
 //# sourceMappingURL=index.js.map

package/dist/server/index.mjs

@@ -15,7 +15,7 @@ import {
   S3Service,
   UserService,
   checkPermissionsFromServer
-} from "../chunk-BIL2WQEV.mjs";
+} from "../chunk-P5TMD7GK.mjs";
 import "../chunk-AUXK7QSA.mjs";
 import "../chunk-C7C7VY4F.mjs";
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",

package/src/components/editors/BlockNoteEditor.tsx

@@ -36,6 +36,7 @@ import {
   XIcon,
 } from "lucide-react";
 import { useTranslations } from "next-intl";
+import { useTheme } from "next-themes";
 import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { getPublicApiUrl } from "../../client/config";
 import { getClientToken } from "../../client/token";
@@ -410,6 +411,7 @@ export default function BlockNoteEditor({
 }: BlockNoteEditorProps): React.JSX.Element {
   const t = useTranslations();
   const locale = useI18nLocale();
+  const { resolvedTheme } = useTheme();
   const { company } = useCurrentUserContext<UserInterface>();
 
   const [acceptedChanges, setAcceptedChanges] = useState<Set<string>>(new Set());
@@ -833,7 +835,9 @@ export default function BlockNoteEditor({
         editable={onChange !== undefined}
         formattingToolbar={false}
         slashMenu={!aiConfig}
-        theme="light"
+        // Follow the app theme: hardcoding "light" leaves dark (light-theme)
+        // text on the dark card, which is nearly unreadable in dark mode.
+        theme={resolvedTheme === "dark" ? "dark" : "light"}
         // `className` is applied by BlockNote to both the main `.bn-container`
         // AND `editor.portalElement` (the floating-UI portal root). Gate `p-4`
         // on `.bn-container` so it doesn't add padding to the empty portal

package/src/components/editors/BlockNoteEditorSuggestionMenuController.tsx

@@ -12,6 +12,16 @@ export interface MentionItem {
   icon?: React.ReactNode;
 }
 
+/**
+ * A suggestion item enriched with the entity it points at. Entity NAMES are not
+ * unique (two clues can both be called "New clue"), so a custom
+ * `suggestionMenuComponent` MUST key its rows on `id`, never on `title`.
+ */
+export type MentionSuggestionItem = DefaultReactSuggestionItem & {
+  id?: string;
+  entityType?: string;
+};
+
 export type MentionSearchFn = (query: string, params?: Record<string, string>) => Promise<MentionItem[]>;
 
 export type MentionInsertFn = (id: string, name: string, entityType: string) => void;
@@ -57,7 +67,9 @@ export function BlockNoteEditorMentionSuggestionMenu({
   const getItems = useCallback(
     async (query: string): Promise<DefaultReactSuggestionItem[]> => {
       const results = await mentionSearchFn(query, mentionSearchParams);
-      const items: DefaultReactSuggestionItem[] = results.map((item) => ({
+      const items: MentionSuggestionItem[] = results.map((item) => ({
+        id: item.id,
+        entityType: item.entityType,
         title: item.name,
         subtext: item.entityType,
         icon: item.icon as React.ReactElement | undefined,
@@ -76,7 +88,7 @@ export function BlockNoteEditorMentionSuggestionMenu({
         },
       }));
       if (items.length === 0) {
-        items.push({ title: KEEP_OPEN_SENTINEL_TITLE, onItemClick: () => {} });
+        items.push({ id: KEEP_OPEN_SENTINEL_TITLE, title: KEEP_OPEN_SENTINEL_TITLE, onItemClick: () => {} });
       }
       return items;
     },

package/src/components/index.ts

@@ -26,6 +26,7 @@ export * from "../features/content/components";
 export * from "../features/how-to/components";
 export * from "../features/assistant/components";
 export * from "../features/assistant-message/components";
+export * from "../features/assistant-action/components";
 export * from "../features/feature/components";
 export * from "../features/notification/components";
 export * from "../features/onboarding/components";

package/src/components/viewers/BlockNoteViewer.tsx

@@ -7,6 +7,7 @@ import type { PartialBlock } from "@blocknote/core";
 // this can render on auth-free public pages.
 import { BlockNoteView } from "@blocknote/shadcn";
 import "@blocknote/shadcn/style.css";
+import { useTheme } from "next-themes";
 
 function normalize(content: unknown): PartialBlock[] | undefined {
   if (Array.isArray(content) && content.length > 0) return content as PartialBlock[];
@@ -23,5 +24,8 @@ function normalize(content: unknown): PartialBlock[] | undefined {
 
 export function BlockNoteViewer({ content }: { content: unknown }) {
   const editor = useCreateBlockNote({ initialContent: normalize(content) });
-  return <BlockNoteView editor={editor} editable={false} theme="light" />;
+  // Outside a next-themes ThemeProvider (public pages) resolvedTheme is
+  // undefined, so this falls back to "light".
+  const { resolvedTheme } = useTheme();
+  return <BlockNoteView editor={editor} editable={false} theme={resolvedTheme === "dark" ? "dark" : "light"} />;
 }

package/src/core/index.ts

@@ -65,6 +65,8 @@ export * from "../features/assistant/AssistantModule";
 export * from "../features/assistant/data";
 export * from "../features/assistant-message/AssistantMessageModule";
 export * from "../features/assistant-message/data";
+export * from "../features/assistant-action/AssistantActionModule";
+export * from "../features/assistant-action/data";
 export * from "../features/chunk/ChunkModule";
 export * from "../features/chunk/data";
 export * from "../features/feature/data";

package/src/core/registry/ModuleRegistry.ts

@@ -18,6 +18,7 @@ export interface FoundationModuleDefinitions {
   HowTo: ModuleWithPermissions;
   Assistant: ModuleWithPermissions;
   AssistantMessage: ModuleWithPermissions;
+  AssistantAction: ModuleWithPermissions;
   Chunk: ModuleWithPermissions;
   // Billing modules - READ: all users, UPDATE: CompanyAdministrator, ADMIN: Administrator
   Billing: ModuleWithPermissions;

package/src/features/assistant/components/containers/AssistantPageContainer.tsx

@@ -0,0 +1,123 @@
+"use client";
+
+import type { DefaultReactSuggestionItem, SuggestionMenuProps } from "@blocknote/react";
+import { Sparkles } from "lucide-react";
+import { useTranslations } from "next-intl";
+import type React from "react";
+import { RoundPageContainer } from "../../../../components/containers/RoundPageContainer";
+import type { MentionResolveFn } from "../../../../components/editors/BlockNoteEditorMentionInlineContent";
+import type { MentionItem } from "../../../../components/editors/BlockNoteEditorSuggestionMenuController";
+import { SectionHeader } from "../../../../components/typography";
+import { Modules } from "../../../../core";
+import type { ApprovalActionRenderer, MentionRenderer } from "../../../assistant-message/components/MessageItem";
+import { useAssistantContext } from "../../contexts/AssistantContext";
+import { AssistantBlockNoteComposer } from "../parts/AssistantBlockNoteComposer";
+import { AssistantSidebar } from "../parts/AssistantSidebar";
+import { AssistantThread } from "../parts/AssistantThread";
+import { AssistantThreadHeader } from "../parts/AssistantThreadHeader";
+
+interface Props {
+  renderApprovalAction?: ApprovalActionRenderer;
+  renderMention?: MentionRenderer;
+  mentionSearchFn?: (query: string, params?: Record<string, string>) => Promise<MentionItem[]>;
+  mentionSearchParams?: Record<string, string>;
+  mentionResolveFn?: MentionResolveFn;
+  /**
+   * Custom mention menu for the composer. Without one BlockNote renders its
+   * default menu, which keys rows on the item title — duplicate entity names
+   * then collide.
+   */
+  suggestionMenuComponent?: React.FC<SuggestionMenuProps<DefaultReactSuggestionItem>>;
+  /** Rendered inside the sidebar's details panel above the thread list. */
+  detailsTitle: string;
+  detailsIcon: React.ReactNode;
+}
+
+/**
+ * Full-page assistant: the thread list lives in the page's details panel and
+ * the conversation fills the card. Unlike `AssistantContainer` the composer is
+ * the BlockNote one, so the very first message of a thread can carry mentions.
+ */
+export function AssistantPageContainer({
+  renderApprovalAction,
+  renderMention,
+  mentionSearchFn,
+  mentionSearchParams,
+  mentionResolveFn,
+  suggestionMenuComponent,
+  detailsTitle,
+  detailsIcon,
+}: Props) {
+  const t = useTranslations();
+  const ctx = useAssistantContext();
+  const showThread = !!ctx.assistant || ctx.sending || ctx.messages.length > 0;
+
+  return (
+    <RoundPageContainer
+      module={Modules.Assistant}
+      fullWidth
+      forceHeader
+      defaultDetailsOpen
+      detailsTitle={detailsTitle}
+      detailsIcon={detailsIcon}
+      details={
+        // The panel supplies its own padding and border; cancel both so the
+        // sidebar reads as the panel body rather than a card inside it.
+        <div className="-m-4 flex h-full min-h-0 [&>aside]:w-full [&>aside]:border-r-0 [&>aside]:bg-transparent">
+          <AssistantSidebar
+            threads={ctx.threads}
+            activeId={ctx.assistant?.id}
+            onSelect={ctx.selectThread}
+            onNew={ctx.startNew}
+          />
+        </div>
+      }
+    >
+      <div className="bg-background flex h-full w-full flex-col overflow-hidden rounded-lg border">
+        {showThread ? (
+          <>
+            {ctx.assistant ? (
+              <AssistantThreadHeader
+                assistant={ctx.assistant}
+                onRename={(title) => ctx.renameThread(ctx.assistant!.id, title)}
+                onDelete={() => ctx.deleteThread(ctx.assistant!.id)}
+              />
+            ) : (
+              <div className="flex items-center justify-between border-b px-5 py-3" aria-hidden>
+                <div className="h-5" />
+              </div>
+            )}
+            <AssistantThread
+              messages={ctx.messages}
+              sending={ctx.sending}
+              status={ctx.status}
+              onSelectFollowUp={ctx.sendMessage}
+              failedMessageIds={ctx.failedMessageIds}
+              onRetry={ctx.retrySend}
+              renderApprovalAction={renderApprovalAction}
+              renderMention={renderMention}
+            />
+          </>
+        ) : (
+          <div className="flex flex-1 items-center justify-center p-10">
+            <div className="flex max-w-2xl flex-col items-center text-center">
+              <span className="mb-3 flex h-10 w-10 items-center justify-center rounded-full bg-gradient-to-br from-blue-400 to-violet-500 text-white">
+                <Sparkles className="h-5 w-5" />
+              </span>
+              <SectionHeader>{t("features.assistant.empty_state.title")}</SectionHeader>
+              <p className="text-muted-foreground mt-1 text-sm">{t("features.assistant.empty_state.subtitle")}</p>
+            </div>
+          </div>
+        )}
+        <AssistantBlockNoteComposer
+          onSend={(content, opts) => ctx.sendMessage(content, { contentBlocks: opts.contentBlocks })}
+          disabled={ctx.sending}
+          mentionSearchFn={mentionSearchFn}
+          mentionSearchParams={mentionSearchParams}
+          mentionResolveFn={mentionResolveFn}
+          suggestionMenuComponent={suggestionMenuComponent}
+        />
+      </div>
+    </RoundPageContainer>
+  );
+}

package/src/features/assistant/components/index.ts

@@ -1 +1,3 @@
 export * from "./containers/AssistantContainer";
+export * from "./containers/AssistantPageContainer";
+export * from "./parts/AssistantBlockNoteComposer";

package/src/features/assistant/components/parts/AssistantBlockNoteComposer.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+import { ArrowUp } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useCallback, useId, useState, type FC, type KeyboardEvent } from "react";
+import type { DefaultReactSuggestionItem, SuggestionMenuProps } from "@blocknote/react";
+import { BlockNoteEditorContainer } from "../../../../components/editors/BlockNoteEditorContainer";
+import type { MentionResolveFn } from "../../../../components/editors/BlockNoteEditorMentionInlineContent";
+import type { MentionItem } from "../../../../components/editors/BlockNoteEditorSuggestionMenuController";
+import { Button } from "../../../../shadcnui";
+
+interface Props {
+  onSend: (content: string, opts: { contentBlocks: unknown[] }) => Promise<void>;
+  disabled?: boolean;
+  mentionSearchFn?: (query: string, params?: Record<string, string>) => Promise<MentionItem[]>;
+  mentionSearchParams?: Record<string, string>;
+  mentionResolveFn?: MentionResolveFn;
+  /**
+   * Custom mention menu. Without one BlockNote renders its default menu, which
+   * keys rows on the item title — duplicate entity names then collide.
+   */
+  suggestionMenuComponent?: FC<SuggestionMenuProps<DefaultReactSuggestionItem>>;
+}
+
+/**
+ * Flattens a BlockNote document to a single plain-text string. This is only a
+ * FALLBACK for the server, which re-derives the stored text from the blocks it
+ * receives — the blocks are the source of truth, never this string.
+ */
+function flattenBlocks(blocks: unknown[]): string {
+  const lines: string[] = [];
+
+  const readInline = (inline: unknown): string => {
+    if (typeof inline === "string") return inline;
+    if (!inline || typeof inline !== "object") return "";
+    const node = inline as { type?: string; text?: string; props?: { alias?: string }; content?: unknown };
+    if (node.type === "mention") return node.props?.alias ?? "";
+    if (typeof node.text === "string") return node.text;
+    if (Array.isArray(node.content)) return node.content.map(readInline).join("");
+    return "";
+  };
+
+  const readBlock = (block: unknown): void => {
+    if (!block || typeof block !== "object") return;
+    const node = block as { content?: unknown; children?: unknown };
+    if (Array.isArray(node.content)) {
+      const line = node.content.map(readInline).join("").trim();
+      if (line) lines.push(line);
+    } else if (typeof node.content === "string" && node.content.trim()) {
+      lines.push(node.content.trim());
+    }
+    if (Array.isArray(node.children)) node.children.forEach(readBlock);
+  };
+
+  blocks.forEach(readBlock);
+  return lines.join("\n");
+}
+
+/**
+ * Mention-capable chat composer. Unlike `AssistantComposer` (plain textarea) it
+ * sends the BlockNote document alongside the flattened text, so the server can
+ * resolve `@`-mentions to real entities and pin them into the agent's focus.
+ */
+export function AssistantBlockNoteComposer({
+  onSend,
+  disabled,
+  mentionSearchFn,
+  mentionSearchParams,
+  mentionResolveFn,
+  suggestionMenuComponent,
+}: Props) {
+  const t = useTranslations();
+  // React's generated ids carry delimiters (`:r0:` / `«r0»`) and this value ends
+  // up inside an S3 object key, so keep it to path-safe characters.
+  const editorId = useId().replace(/[^a-zA-Z0-9]/g, "");
+  const [blocks, setBlocks] = useState<unknown[]>([]);
+  const [isEmpty, setIsEmpty] = useState(true);
+  // Remounting the editor is the only reliable way to clear it: the editor
+  // ignores an `initialContent` that merely echoes what it last emitted.
+  const [resetKey, setResetKey] = useState(0);
+
+  const canSend = !isEmpty && !disabled;
+
+  const submit = useCallback(async () => {
+    if (isEmpty || disabled) return;
+    const payload = blocks;
+    const plainText = flattenBlocks(payload);
+    setBlocks([]);
+    setIsEmpty(true);
+    setResetKey((previous) => previous + 1);
+    await onSend(plainText, { contentBlocks: payload });
+  }, [blocks, disabled, isEmpty, onSend]);
+
+  const handleKeyDownCapture = useCallback(
+    (event: KeyboardEvent<HTMLDivElement>) => {
+      if (event.key !== "Enter" || event.shiftKey) return;
+      // The mention suggestion menu claims Enter with a CAPTURING document
+      // listener of its own. If we preventDefault here the highlighted mention
+      // is never inserted, so stand down whenever the menu is on screen.
+      if (typeof document !== "undefined" && document.querySelector(".bn-suggestion-menu")) return;
+      event.preventDefault();
+      void submit();
+    },
+    [submit],
+  );
+
+  return (
+    <div className="flex flex-col gap-1 border-t p-4">
+      <div className="bg-muted/30 flex items-end gap-2 rounded-lg border p-2">
+        <div className="max-h-40 min-w-0 flex-1 overflow-y-auto" onKeyDownCapture={handleKeyDownCapture}>
+          <BlockNoteEditorContainer
+            key={resetKey}
+            id={editorId}
+            type="assistants"
+            placeholder={t("features.assistant.composer_placeholder")}
+            enableMentions
+            mentionSearchFn={mentionSearchFn}
+            mentionSearchParams={mentionSearchParams}
+            mentionResolveFn={mentionResolveFn}
+            suggestionMenuComponent={suggestionMenuComponent}
+            onChange={(content: unknown, empty: boolean) => {
+              setBlocks(Array.isArray(content) ? content : []);
+              setIsEmpty(empty);
+            }}
+            className="[&_.bn-container]:!p-0"
+          />
+        </div>
+        <Button onClick={submit} disabled={!canSend} size="sm" className="h-8">
+          <ArrowUp className="mr-1 h-4 w-4" /> {t("features.assistant.send")}
+        </Button>
+      </div>
+      <div className="text-muted-foreground text-right text-xs">{t("features.assistant.keyboard_hint")}</div>
+    </div>
+  );
+}

package/src/features/assistant/components/parts/AssistantThread.tsx

@@ -3,7 +3,7 @@
 import { useEffect, useRef } from "react";
 import type { AssistantMessageInterface } from "../../../assistant-message/data/AssistantMessageInterface";
 import { MessageList } from "../../../assistant-message/components/MessageList";
-import type { ApprovalActionRenderer } from "../../../assistant-message/components/MessageItem";
+import type { ApprovalActionRenderer, MentionRenderer } from "../../../assistant-message/components/MessageItem";
 import { AssistantStatusLine } from "./AssistantStatusLine";
 
 interface Props {
@@ -14,6 +14,7 @@ interface Props {
   failedMessageIds?: Set<string>;
   onRetry?: (tempId: string) => void;
   renderApprovalAction?: ApprovalActionRenderer;
+  renderMention?: MentionRenderer;
 }
 
 export function AssistantThread({
@@ -24,6 +25,7 @@ export function AssistantThread({
   failedMessageIds,
   onRetry,
   renderApprovalAction,
+  renderMention,
 }: Props) {
   const endRef = useRef<HTMLDivElement>(null);
 
@@ -39,6 +41,7 @@ export function AssistantThread({
         failedMessageIds={failedMessageIds}
         onRetry={onRetry}
         renderApprovalAction={renderApprovalAction}
+        renderMention={renderMention}
       />
       {sending && <AssistantStatusLine status={status} />}
       <div ref={endRef} />

package/src/features/assistant/contexts/AssistantContext.tsx

@@ -20,7 +20,10 @@ interface AssistantContextValue {
   sending: boolean;
   status?: string;
   failedMessageIds: Set<string>;
-  sendMessage(content: string, opts?: { howToMode?: boolean; limitToHowToId?: string }): Promise<void>;
+  sendMessage(
+    content: string,
+    opts?: { howToMode?: boolean; limitToHowToId?: string; contentBlocks?: unknown[] },
+  ): Promise<void>;
   retrySend(tempId: string): Promise<void>;
   selectThread(id: string): Promise<void>;
   startNew(): void;
@@ -46,6 +49,28 @@ interface Props {
    * current route is preserved.
    */
   manageUrl?: boolean;
+  /**
+   * Confines the provider to one bound resource (e.g. a campaign): the thread
+   * list is filtered to that resource and newly created threads are bound to
+   * it, so a scoped surface never shows or creates cross-scope threads.
+   */
+  scope?: { type: string; id: string };
+  /**
+   * Builds the browser URL for a thread. Defaults to `/assistants/{id}` (or
+   * `/assistants` when no thread is active), which is only correct for the
+   * standalone assistant route; a scoped host passes its own builder.
+   */
+  threadUrl?: (id?: string) => string;
+  /**
+   * Page heading. Defaults to the "Assistants" entity label; a scoped host
+   * passes something meaningful for its own surface.
+   */
+  titleOverride?: string;
+  /**
+   * Breadcrumb trail. Defaults to a single crumb pointing at the global
+   * assistant list, which is wrong for a scoped surface.
+   */
+  breadcrumbsOverride?: BreadcrumbItemData[];
 }
 
 function stripOptimistic(list: AssistantMessageInterface[]): AssistantMessageInterface[] {
@@ -67,10 +92,24 @@ function withPatchedTitle(source: AssistantInterface, title: string): AssistantI
   });
 }
 
-export function AssistantProvider({ children, dehydratedAssistant, dehydratedMessages, manageUrl = true }: Props) {
+export function AssistantProvider({
+  children,
+  dehydratedAssistant,
+  dehydratedMessages,
+  manageUrl = true,
+  titleOverride,
+  breadcrumbsOverride,
+  scope,
+  threadUrl,
+}: Props) {
   const t = useTranslations();
   const generateUrl = usePageUrlGenerator();
 
+  const resolveThreadUrl = useCallback(
+    (id?: string) => (threadUrl ? threadUrl(id) : id ? `/assistants/${id}` : "/assistants"),
+    [threadUrl],
+  );
+
   const [assistant, setAssistant] = useState<AssistantInterface | undefined>(() =>
     dehydratedAssistant ? rehydrate<AssistantInterface>(Modules.Assistant, dehydratedAssistant) : undefined,
   );
@@ -91,7 +130,7 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
   const { socket } = useSocketContext();
 
   const sendMessage = useCallback(
-    async (content: string, opts?: { howToMode?: boolean; limitToHowToId?: string }) => {
+    async (content: string, opts?: { howToMode?: boolean; limitToHowToId?: string; contentBlocks?: unknown[] }) => {
       const trimmed = content.trim();
       if (!trimmed) return;
 
@@ -116,6 +155,8 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
             firstMessage: trimmed,
             howToMode: opts?.howToMode,
             limitToHowToId: opts?.limitToHowToId,
+            contentBlocks: opts?.contentBlocks,
+            boundContent: scope,
           };
           const created = operatorMode
             ? await AssistantService.createOperator(input)
@@ -125,19 +166,21 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
           setMessages(msgs);
           setThreads((prev) => [created, ...prev]);
           if (manageUrl && typeof window !== "undefined") {
-            window.history.replaceState(null, "", `/assistants/${created.id}`);
+            window.history.replaceState(null, "", resolveThreadUrl(created.id));
           }
         } else {
           const result = operatorMode
             ? await AssistantService.appendMessageOperator({
                 assistantId: assistant.id,
                 content: trimmed,
+                contentBlocks: opts?.contentBlocks,
               })
             : await AssistantService.appendMessage({
                 assistantId: assistant.id,
                 content: trimmed,
                 howToMode: opts?.howToMode,
                 limitToHowToId: opts?.limitToHowToId,
+                contentBlocks: opts?.contentBlocks,
               });
           setMessages((prev) => [...stripOptimistic(prev), ...result]);
         }
@@ -153,7 +196,7 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
         setStatus(undefined);
       }
     },
-    [assistant, messages, socket, operatorMode],
+    [assistant, messages, socket, operatorMode, scope, manageUrl, resolveThreadUrl],
   );
 
   const appendResolvedMessage = useCallback((message: AssistantMessageInterface) => {
@@ -191,10 +234,10 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
       // absent) keeps the default responder flow.
       setOperatorMode(target.engine === "operator");
       if (manageUrl && typeof window !== "undefined") {
-        window.history.replaceState(null, "", `/assistants/${id}`);
+        window.history.replaceState(null, "", resolveThreadUrl(id));
       }
     },
-    [manageUrl],
+    [manageUrl, resolveThreadUrl],
   );
 
   const renameThread = useCallback(async (id: string, title: string) => {
@@ -209,9 +252,9 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
     setFailedMessageIds(new Set());
     setOperatorMode(false);
     if (manageUrl && typeof window !== "undefined") {
-      window.history.replaceState(null, "", "/assistants");
+      window.history.replaceState(null, "", resolveThreadUrl());
     }
-  }, [manageUrl]);
+  }, [manageUrl, resolveThreadUrl]);
 
   const deleteThread = useCallback(async (id: string) => {
     await AssistantService.delete({ id });
@@ -230,7 +273,7 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
     (async () => {
       setThreadsLoading(true);
       try {
-        const loaded = await AssistantService.findMany();
+        const loaded = await AssistantService.findMany({ boundType: scope?.type, boundId: scope?.id });
         if (!cancelled) setThreads(loaded);
       } finally {
         if (!cancelled) setThreadsLoading(false);
@@ -239,7 +282,7 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
     return () => {
       cancelled = true;
     };
-  }, []);
+  }, [scope?.type, scope?.id]);
 
   const value = useMemo<AssistantContextValue>(
     () => ({
@@ -279,15 +322,19 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
     ],
   );
 
-  const breadcrumbs: BreadcrumbItemData[] = [
+  // A scoped assistant lives under its host resource, so the default trail to
+  // the global /assistants list is wrong there — the consumer supplies its own.
+  const breadcrumbs: BreadcrumbItemData[] = breadcrumbsOverride ?? [
     {
       name: t("entities.assistants", { count: 2 }),
       href: generateUrl({ page: Modules.Assistant }),
     },
   ];
 
+  // `entities.tasks` was a copy-paste from another feature and rendered
+  // "Tasks" as the page heading of every assistant page.
   const title = {
-    type: t("entities.tasks", { count: 2 }),
+    type: titleOverride ?? t("entities.assistants", { count: 2 }),
   };
 
   return (