@carlonicora/nextjs-jsonapi 3.11.0 → 3.13.0

package/src/core/registry/ModuleRegistry.ts

@@ -16,6 +16,10 @@ export interface FoundationModuleDefinitions {
   Module: ModuleWithPermissions;
   Content: ModuleWithPermissions;
   HowTo: ModuleWithPermissions;
+  HandbookPage: ModuleWithPermissions;
+  HandbookSection: ModuleWithPermissions;
+  HandbookThread: ModuleWithPermissions;
+  HandbookThreadMessage: ModuleWithPermissions;
   Assistant: ModuleWithPermissions;
   AssistantMessage: ModuleWithPermissions;
   AssistantAction: ModuleWithPermissions;

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

@@ -10,9 +10,28 @@ interface Props {
   disabled?: boolean;
   value?: string;
   onValueChange?: (v: string) => void;
+  /**
+   * Textarea placeholder. Defaults to the assistant's own copy ("ask me about a
+   * matter, a client, a document…"), which is wrong on any surface that is not
+   * the law-firm assistant.
+   */
+  placeholder?: string;
+  /**
+   * Label of the send button. Defaults to `ui.buttons.save`, which reads
+   * "Salva" — correct nowhere in a chat, kept only so existing callers do not
+   * move.
+   */
+  sendLabel?: string;
 }
 
-export function AssistantComposer({ onSend, disabled, value: controlled, onValueChange }: Props) {
+export function AssistantComposer({
+  onSend,
+  disabled,
+  value: controlled,
+  onValueChange,
+  placeholder,
+  sendLabel,
+}: Props) {
   const t = useTranslations();
   const [internal, setInternal] = useState("");
   const value = controlled ?? internal;
@@ -41,13 +60,13 @@ export function AssistantComposer({ onSend, disabled, value: controlled, onValue
           value={value}
           onChange={(e) => setValue(e.target.value)}
           onKeyDown={onKeyDown}
-          placeholder={t("features.assistant.composer_placeholder")}
+          placeholder={placeholder ?? t("features.assistant.composer_placeholder")}
           disabled={disabled}
           rows={2}
           className="min-h-[48px] resize-none border-0 bg-transparent focus-visible:ring-0"
         />
         <Button onClick={submit} disabled={!canSend} size="sm" className="h-8">
-          <ArrowUp className="me-1 h-4 w-4" /> {t("features.assistant.send")}
+          <ArrowUp className="me-1 h-4 w-4" /> {sendLabel ?? t("features.assistant.send")}
         </Button>
       </div>
       <div className="text-muted-foreground text-end text-xs">{t("features.assistant.keyboard_hint")}</div>

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

@@ -12,9 +12,17 @@ interface Props {
   activeId?: string;
   onSelect: (id: string) => void;
   onNew: () => void;
+  /**
+   * Label of the "start a new thread" button. Defaults to the assistant's own
+   * copy; a surface that is not the assistant (the handbook chat) passes its
+   * own so the control does not read "New assistant" on a handbook page.
+   */
+  newLabel?: string;
+  /** Shown when there are no threads. Same rationale as `newLabel`. */
+  emptyLabel?: string;
 }
 
-export function AssistantSidebar({ threads, activeId, onSelect, onNew }: Props) {
+export function AssistantSidebar({ threads, activeId, onSelect, onNew, newLabel, emptyLabel }: Props) {
   const t = useTranslations();
   const groups = groupThreadsByBucket(threads);
 
@@ -44,12 +52,14 @@ export function AssistantSidebar({ threads, activeId, onSelect, onNew }: Props)
     <aside className="bg-muted/30 flex w-64 flex-col border-e">
       <div className="border-b p-3">
         <Button onClick={onNew} className="w-full" size="sm">
-          <Plus className="me-1 h-4 w-4" /> {t("features.assistant.new")}
+          <Plus className="me-1 h-4 w-4" /> {newLabel ?? t("features.assistant.new")}
         </Button>
       </div>
       <div className="flex-1 overflow-y-auto p-2">
         {threads.length === 0 ? (
-          <div className="text-muted-foreground mt-6 text-center text-xs">{t("features.assistant.empty_sidebar")}</div>
+          <div className="text-muted-foreground mt-6 text-center text-xs">
+            {emptyLabel ?? t("features.assistant.empty_sidebar")}
+          </div>
         ) : (
           <>
             {renderSection(t("features.assistant.bucket_today"), groups.today)}

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

@@ -21,9 +21,16 @@ interface Props {
   assistant: AssistantInterface;
   onRename: (title: string) => Promise<void>;
   onDelete: () => Promise<void>;
+  /**
+   * Placeholder of the rename field. Defaults to the assistant's own copy
+   * ("name this assistant"), which misnames the thread on any other surface.
+   */
+  renamePlaceholder?: string;
+  /** Body of the delete confirmation. Same rationale as `renamePlaceholder`. */
+  deleteConfirmLabel?: string;
 }
 
-export function AssistantThreadHeader({ assistant, onRename, onDelete }: Props) {
+export function AssistantThreadHeader({ assistant, onRename, onDelete, renamePlaceholder, deleteConfirmLabel }: Props) {
   const t = useTranslations();
   const [renameValue, setRenameValue] = useState(assistant.title);
   const [renameOpen, setRenameOpen] = useState(false);
@@ -56,7 +63,7 @@ export function AssistantThreadHeader({ assistant, onRename, onDelete }: Props)
             <Input
               value={renameValue}
               onChange={(e) => setRenameValue(e.target.value)}
-              placeholder={t("features.assistant.rename_placeholder")}
+              placeholder={renamePlaceholder ?? t("features.assistant.rename_placeholder")}
             />
             <Button onClick={handleRename} size="sm">
               {t("ui.buttons.save")}
@@ -73,7 +80,7 @@ export function AssistantThreadHeader({ assistant, onRename, onDelete }: Props)
           />
           <DialogContent>
             <DialogHeader>
-              <DialogTitle>{t("features.assistant.delete_confirm")}</DialogTitle>
+              <DialogTitle>{deleteConfirmLabel ?? t("features.assistant.delete_confirm")}</DialogTitle>
             </DialogHeader>
             <DialogFooter>
               <Button variant="outline" onClick={() => setDeleteOpen(false)}>

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

@@ -22,7 +22,13 @@ interface AssistantContextValue {
   failedMessageIds: Set<string>;
   sendMessage(
     content: string,
-    opts?: { howToMode?: boolean; limitToHowToId?: string; contentBlocks?: unknown[] },
+    opts?: {
+      howToMode?: boolean;
+      limitToHowToId?: string;
+      handbookMode?: boolean;
+      limitToHandbookPageId?: string;
+      contentBlocks?: unknown[];
+    },
   ): Promise<void>;
   retrySend(tempId: string): Promise<void>;
   selectThread(id: string): Promise<void>;
@@ -55,6 +61,13 @@ interface Props {
    * it, so a scoped surface never shows or creates cross-scope threads.
    */
   scope?: { type: string; id: string };
+  /**
+   * Confines every turn of this provider to one retrieval mode. The handbook
+   * surface sets `{ handbookMode: true }` so the flag does not have to be
+   * threaded through the composer on each send — the same reason `scope`
+   * exists on this provider.
+   */
+  retrievalMode?: { handbookMode?: boolean; limitToHandbookPageId?: 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
@@ -100,6 +113,7 @@ export function AssistantProvider({
   titleOverride,
   breadcrumbsOverride,
   scope,
+  retrievalMode,
   threadUrl,
 }: Props) {
   const t = useTranslations();
@@ -130,7 +144,16 @@ export function AssistantProvider({
   const { socket } = useSocketContext();
 
   const sendMessage = useCallback(
-    async (content: string, opts?: { howToMode?: boolean; limitToHowToId?: string; contentBlocks?: unknown[] }) => {
+    async (
+      content: string,
+      opts?: {
+        howToMode?: boolean;
+        limitToHowToId?: string;
+        handbookMode?: boolean;
+        limitToHandbookPageId?: string;
+        contentBlocks?: unknown[];
+      },
+    ) => {
       const trimmed = content.trim();
       if (!trimmed) return;
 
@@ -155,6 +178,8 @@ export function AssistantProvider({
             firstMessage: trimmed,
             howToMode: opts?.howToMode,
             limitToHowToId: opts?.limitToHowToId,
+            handbookMode: opts?.handbookMode ?? retrievalMode?.handbookMode,
+            limitToHandbookPageId: opts?.limitToHandbookPageId ?? retrievalMode?.limitToHandbookPageId,
             contentBlocks: opts?.contentBlocks,
             boundContent: scope,
           };
@@ -180,6 +205,8 @@ export function AssistantProvider({
                 content: trimmed,
                 howToMode: opts?.howToMode,
                 limitToHowToId: opts?.limitToHowToId,
+                handbookMode: opts?.handbookMode ?? retrievalMode?.handbookMode,
+                limitToHandbookPageId: opts?.limitToHandbookPageId ?? retrievalMode?.limitToHandbookPageId,
                 contentBlocks: opts?.contentBlocks,
               });
           setMessages((prev) => [...stripOptimistic(prev), ...result]);
@@ -196,7 +223,7 @@ export function AssistantProvider({
         setStatus(undefined);
       }
     },
-    [assistant, messages, socket, operatorMode, scope, manageUrl, resolveThreadUrl],
+    [assistant, messages, socket, operatorMode, scope, retrievalMode, manageUrl, resolveThreadUrl],
   );
 
   const appendResolvedMessage = useCallback((message: AssistantMessageInterface) => {

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

@@ -455,6 +455,38 @@ describe("AssistantContext", () => {
     );
   });
 
+  it("forwards handbookMode passed on the send", async () => {
+    const existing = buildAssistantDehydrated({ id: "a-3", title: "Existing" });
+    AssistantService.appendMessage = vi.fn().mockResolvedValue([]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider dehydratedAssistant={existing}>{children}</AssistantProvider>,
+    });
+    await act(async () => {
+      await result.current.sendMessage("Come funziona il modulo chunk?", { handbookMode: true });
+    });
+
+    expect(AssistantService.appendMessage).toHaveBeenCalledWith(expect.objectContaining({ handbookMode: true }));
+  });
+
+  it("forwards the provider's retrievalMode when the send passes nothing", async () => {
+    const existing = buildAssistantDehydrated({ id: "a-4", title: "Existing" });
+    AssistantService.appendMessage = vi.fn().mockResolvedValue([]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => (
+        <AssistantProvider dehydratedAssistant={existing} retrievalMode={{ handbookMode: true }}>
+          {children}
+        </AssistantProvider>
+      ),
+    });
+    await act(async () => {
+      await result.current.sendMessage("Come funziona il modulo chunk?");
+    });
+
+    expect(AssistantService.appendMessage).toHaveBeenCalledWith(expect.objectContaining({ handbookMode: true }));
+  });
+
   it("calls service without opts when called with content only (regression)", async () => {
     const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
     const created = buildAssistantStub({ id: "a-1" });

package/src/features/assistant/data/Assistant.ts

@@ -58,6 +58,8 @@ export class Assistant extends AbstractApiData implements AssistantInterface {
           ...(data.title !== undefined ? { title: data.title } : {}),
           ...(data.howToMode !== undefined ? { howToMode: data.howToMode } : {}),
           ...(data.limitToHowToId !== undefined ? { limitToHowToId: data.limitToHowToId } : {}),
+          ...(data.handbookMode !== undefined ? { handbookMode: data.handbookMode } : {}),
+          ...(data.limitToHandbookPageId !== undefined ? { limitToHandbookPageId: data.limitToHandbookPageId } : {}),
         },
         ...(data.boundContent !== undefined
           ? {

package/src/features/assistant/data/AssistantInterface.ts

@@ -5,6 +5,8 @@ export type AssistantInput = {
   title?: string;
   howToMode?: boolean;
   limitToHowToId?: string;
+  handbookMode?: boolean;
+  limitToHandbookPageId?: string;
   /**
    * BlockNote document behind `firstMessage`. Sent alongside the flattened
    * text so the server can re-derive the content and read `@`-mentions from

package/src/features/assistant/data/AssistantService.ts

@@ -67,6 +67,8 @@ export class AssistantService extends AbstractService {
     content: string;
     howToMode?: boolean;
     limitToHowToId?: string;
+    handbookMode?: boolean;
+    limitToHandbookPageId?: string;
     /** BlockNote document. Serialised by the model into `content`; never its own attribute. */
     contentBlocks?: unknown[];
   }): Promise<AssistantMessageInterface[]> {
@@ -83,6 +85,8 @@ export class AssistantService extends AbstractService {
         content: params.content,
         howToMode: params.howToMode,
         limitToHowToId: params.limitToHowToId,
+        handbookMode: params.handbookMode,
+        limitToHandbookPageId: params.limitToHandbookPageId,
         contentBlocks: params.contentBlocks,
       }),
       overridesJsonApiCreation: true,

package/src/features/assistant-message/components/parts/MessageSourcesContainer.tsx

@@ -87,7 +87,11 @@ export function MessageSourcesContainer({ message, isLatestAssistant, onSelectFo
 
   useEffect(() => {
     if (groups.size === 0) {
-      setResolved([]);
+      // Functional update, and a no-op when it is already empty. A bare
+      // `setResolved([])` sets a NEW array on every run, so a caller whose
+      // `message.citations` identity changes per render loops here until React
+      // gives up with "Maximum update depth exceeded".
+      setResolved((current) => (current.length === 0 ? current : []));
       return;
     }
     let cancelled = false;

package/src/features/assistant-message/data/AssistantMessage.ts

@@ -129,6 +129,8 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
     content: string;
     howToMode?: boolean;
     limitToHowToId?: string;
+    handbookMode?: boolean;
+    limitToHandbookPageId?: string;
     contentBlocks?: unknown[];
   }) {
     return {
@@ -142,18 +144,41 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
           content: params.contentBlocks !== undefined ? JSON.stringify(params.contentBlocks) : params.content,
           ...(params.howToMode !== undefined ? { howToMode: params.howToMode } : {}),
           ...(params.limitToHowToId !== undefined ? { limitToHowToId: params.limitToHowToId } : {}),
+          ...(params.handbookMode !== undefined ? { handbookMode: params.handbookMode } : {}),
+          ...(params.limitToHandbookPageId !== undefined
+            ? { limitToHandbookPageId: params.limitToHandbookPageId }
+            : {}),
         },
       },
     };
   }
 
   static buildOptimistic(params: { content: string; position: number; assistantId?: string }): AssistantMessage {
+    return AssistantMessage.buildLocal({ ...params, role: "user", isOptimistic: true });
+  }
+
+  /**
+   * A message that exists only on the client, for a surface that renders the
+   * chat presentation without persisting a thread.
+   *
+   * `buildOptimistic` is the user-turn case and delegates here. The handbook
+   * ask surface is the other caller: it has no Assistant and no stored
+   * messages, but it renders through MessageList/MessageItem like every other
+   * chat in the product, so it needs both roles.
+   */
+  static buildLocal(params: {
+    role: AssistantMessageRole;
+    content: string;
+    position: number;
+    assistantId?: string;
+    isOptimistic?: boolean;
+  }): AssistantMessage {
     const msg = new AssistantMessage();
     const jsonApi: Record<string, unknown> = {
       id: uuidv4(),
       type: Modules.AssistantMessage.name,
       attributes: {
-        role: "user",
+        role: params.role,
         content: params.content,
         position: params.position,
       },
@@ -164,7 +189,7 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
       };
     }
     msg.rehydrate({ jsonApi: jsonApi as any, included: [] });
-    msg._isOptimistic = true;
+    msg._isOptimistic = params.isOptimistic ?? false;
     return msg;
   }
 }

package/src/features/billing/i18n-keys.ts

@@ -36,6 +36,7 @@ export const BILLING_ADMIN_I18N_KEYS = [
   "billing.admin.prices.create",
   "billing.admin.prices.empty.title",
   "billing.admin.prices.empty.description",
+  "billing.admin.prices.fields.actions",
   "billing.admin.prices.fields.product",
   "billing.admin.prices.fields.nickname",
   "billing.admin.prices.fields.amount",
@@ -79,6 +80,12 @@ export const BILLING_ADMIN_I18N_KEYS = [
   "billing.admin.prices.immutability.description",
   "billing.admin.prices.actions.addFeature",
   "billing.admin.prices.actions.removeFeature",
+  "billing.admin.prices.actions.clone",
+  "billing.admin.prices.actions.export",
+  "billing.admin.prices.actions.import",
+  "billing.admin.prices.import.errors.title",
+  "billing.admin.prices.import.errors.invalid",
+  "billing.admin.prices.import.warnings.unknownFeatures",
   "billing.admin.prices.archive.title",
   "billing.admin.prices.archive.description",
   "billing.admin.prices.archive.confirm",

package/src/features/billing/stripe-price/components/forms/PriceEditor.tsx

@@ -3,7 +3,7 @@
 import { zodResolver } from "@hookform/resolvers/zod";
 import { PlusIcon, XIcon } from "lucide-react";
 import { useTranslations } from "next-intl";
-import { ReactNode, useCallback, useEffect, useMemo, useState } from "react";
+import { ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useForm } from "react-hook-form";
 import { v4 } from "uuid";
 import { z } from "zod";
@@ -11,13 +11,27 @@ import { EditorSheet, FieldLabel, FormCheckbox, FormInput, FormSelect, FormTexta
 import { Modules } from "../../../../../core";
 import { useI18nRouter } from "../../../../../i18n";
 import { Alert, AlertDescription, AlertTitle, Button, Checkbox, Input } from "../../../../../shadcnui";
+import { showToast } from "../../../../../utils/toast";
 import { FeatureInterface, FeatureService } from "../../../../feature";
 import { priceLabel, usePriceContext } from "../../../contexts/PriceContext";
 import { StripePriceInput, StripePriceInterface } from "../../data/stripe-price.interface";
+import { StripePriceSeed } from "../../data/stripe-price.transfer";
 
 export type PriceEditorProps = {
   productId?: string;
   price?: StripePriceInterface;
+  /**
+   * Pre-fills a NEW price — the Clone (a row in the prices list) and Import (a
+   * JSON document) paths both hand over the same seed.
+   *
+   * The seed deliberately carries NO identity: no Stripe price id, no internal
+   * id and no product id. A clone/import is a brand-new price, minted fresh by
+   * Stripe and attached to whatever product this editor is mounted for
+   * (`productId` / the context), so copying any identity across would either
+   * collide or silently re-point the new price at the source environment's
+   * objects. Seeding therefore never makes this an edit — see `isEdit` below.
+   */
+  seed?: StripePriceSeed;
   propagateChanges?: (price: StripePriceInterface) => void;
   onSuccess?: () => void | Promise<void>;
   trigger?: ReactNode;
@@ -30,6 +44,7 @@ export type PriceEditorProps = {
 function PriceEditorInternal({
   productId,
   price,
+  seed,
   propagateChanges,
   onSuccess,
   trigger,
@@ -42,6 +57,9 @@ function PriceEditorInternal({
   const router = useI18nRouter();
   const { createPrice, updatePrice, productId: contextProductId } = usePriceContext();
   const [allFeatures, setAllFeatures] = useState<FeatureInterface[]>([]);
+  // Stays `!!price`, never `!!price || !!seed`: a seeded editor is a CREATE, so
+  // the create branch of onSubmit (fresh v4(), targetProductId, no id reuse)
+  // must run for it exactly as it does for an empty form.
   const isEdit = !!price;
   // NOT `price.productId` — that getter throws when the attribute is absent, and
   // it always is (see the note in PriceContext). Only create mode needs this,
@@ -106,6 +124,24 @@ function PriceEditorInternal({
 
   type PriceFormValues = z.infer<typeof formSchema>;
 
+  // Seeds carry platform features as NAMES, never ids: Feature ids differ per
+  // environment, names are the stable handle. A name this environment does not
+  // know is DROPPED rather than failing the whole seed — the effect below
+  // reports the dropped ones once.
+  const resolvePlatformFeatures = useCallback(
+    (names: string[] | undefined): { ids: string[]; unknown: string[] } => {
+      const ids: string[] = [];
+      const unknown: string[] = [];
+      for (const name of names ?? []) {
+        const match = allFeatures.find((feature) => feature.name === name);
+        if (match) ids.push(match.id);
+        else unknown.push(name);
+      }
+      return { ids, unknown };
+    },
+    [allFeatures],
+  );
+
   // Fed to BOTH useForm and EditorSheet.onReset. The previous implementation
   // reseeded with its own `useEffect(… form.reset)` on open; EditorSheet already
   // owns that (EditorSheet.tsx:163-190) and running both fights over the form.
@@ -114,6 +150,30 @@ function PriceEditorInternal({
   // (PriceArchiver), and a second toggle here would let the two disagree.
   const getDefaultValues = useCallback((): PriceFormValues => {
     const coreFeatureIds = allFeatures.filter((feature) => feature.isCore).map((feature) => feature.id);
+
+    // Seed branch: create mode only (`price` always wins — an edit form must
+    // show the price it edits, never a seed). Mirrors the `price` branch below
+    // field for field, including the /100: the seed keeps Stripe's MINOR units
+    // while the form field is in MAJOR units.
+    if (!price && seed) {
+      return {
+        unitAmount: seed.unitAmount / 100,
+        currency: seed.currency,
+        interval: seed.interval,
+        intervalCount: seed.intervalCount ?? 1,
+        usageType: seed.usageType ?? "licensed",
+        nickname: seed.nickname ?? "",
+        isTrial: seed.isTrial ?? false,
+        description: seed.description ?? "",
+        features: seed.features ?? [],
+        // `.toString()`, for the same reason the schema keeps the token
+        // pipeline string-based: a seeded `0` must survive as "0" and not be
+        // dropped as falsy.
+        token: seed.token?.toString() ?? "",
+        featureIds: [...new Set([...resolvePlatformFeatures(seed.platformFeatures).ids, ...coreFeatureIds])],
+      };
+    }
+
     return {
       unitAmount: price?.unitAmount ? price.unitAmount / 100 : 0,
       currency: price?.currency ?? "usd",
@@ -127,13 +187,59 @@ function PriceEditorInternal({
       token: price?.token?.toString() ?? "",
       featureIds: [...new Set([...(price?.priceFeatures?.map((f) => f.id) ?? []), ...coreFeatureIds])],
     };
-  }, [price, allFeatures]);
+  }, [price, seed, allFeatures, resolvePlatformFeatures]);
 
   const form = useForm<PriceFormValues>({
     resolver: zodResolver(formSchema) as any,
     defaultValues: getDefaultValues(),
   });
 
+  // ── The seeding race ──────────────────────────────────────────────────────
+  // `getDefaultValues` reads `allFeatures`, which the fetch effect above
+  // resolves asynchronously — so `useForm` has ALREADY seeded from an empty
+  // list by the time the features land, and every id-bearing default
+  // (`featureIds`: the core features, plus whatever the seed named) is missing.
+  //
+  // Nothing else fixes it: EditorSheet re-seeds on open only when `isEdit`
+  // (EditorSheet.tsx:209 — create defaults usually contain a fresh uuid, so an
+  // unconditional reset there would fire on every open and clobber parents that
+  // pre-fill via form.setValue). That is exactly why the core-feature
+  // checkboxes come up empty on a first create today.
+  //
+  // So catch up here, once, and only when it is safe:
+  //  - `!isEdit`      — the edit path is EditorSheet's, do not fight it.
+  //  - `length > 0`   — this is the empty → loaded transition, not the initial
+  //                     render (and not a genuinely empty feature list).
+  //  - the ref        — one shot per mount, so a later `allFeatures` identity
+  //                     change cannot re-reset a form the user is using.
+  //  - `!isDirty`     — never clobber anything already typed; a user who edited
+  //                     before the fetch returned keeps their input, and the
+  //                     one-shot ref is burned either way.
+  const hasCaughtUpWithFeatures = useRef(false);
+  useEffect(() => {
+    if (isEdit || hasCaughtUpWithFeatures.current || allFeatures.length === 0) return;
+    hasCaughtUpWithFeatures.current = true;
+    if (form.formState.isDirty) return;
+    form.reset(getDefaultValues());
+  }, [allFeatures, isEdit, form, getDefaultValues]);
+
+  // Unknown platform feature names are reported ONCE per seed, not per render:
+  // `seed` typically arrives as an object literal from the list row or the
+  // import dialog, so its identity changes on every parent render — the guard
+  // keys on the names themselves instead. Waits for `allFeatures`, since before
+  // the fetch resolves every name looks unknown.
+  const warnedUnknownFor = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    if (isEdit || !seed || allFeatures.length === 0) return;
+    const fingerprint = JSON.stringify(seed.platformFeatures ?? []);
+    if (warnedUnknownFor.current === fingerprint) return;
+    warnedUnknownFor.current = fingerprint;
+
+    const { unknown } = resolvePlatformFeatures(seed.platformFeatures);
+    if (unknown.length > 0)
+      showToast(t("billing.admin.prices.import.warnings.unknownFeatures", { features: unknown.join(", ") }));
+  }, [seed, isEdit, allFeatures, resolvePlatformFeatures, t]);
+
   const watchInterval = form.watch("interval");
   const isRecurring = watchInterval !== "one_time";