create-nextblock 0.15.9 → 0.16.1

package/templates/nextblock-template/app/cms/media/components/MediaEditForm.tsx

@@ -15,7 +15,67 @@ import { useHotkeys } from '../../../../hooks/use-hotkeys';
 import { resolveMediaUrl } from '../../../../lib/media/resolveMediaUrl';
 
 type Media = Database['public']['Tables']['media']['Row'];
-import { FileText } from 'lucide-react';
+import { FileText, Loader2, Sparkles } from 'lucide-react';
+import { toast } from 'sonner';
+import { useCortexAiActive } from '../../components/CortexAiActiveContext';
+import { buildCortexAiRequestHeaders } from '../../../../lib/cortex-ai/sandbox-headers';
+import {
+  buildAltTextContext,
+  toAbsoluteImageUrl,
+  UNRESOLVABLE_IMAGE_URL_MESSAGE,
+} from '../../../../lib/cortex-ai/alt-text-request';
+// The label the upload pipeline gives the untouched original file among a row's
+// `variants`. It currently lives in the email module because email was the first consumer
+// that needed the non-AVIF original; the constant itself is about the media pipeline, not
+// about email, so importing it here is reuse rather than a layering violation — and it is
+// far better than a second copy of the string drifting away from the pipeline that writes it.
+import { ORIGINAL_UPLOAD_VARIANT_LABEL } from '../../../../lib/email/branding-format';
+
+/** The `variants` JSONB rows the upload pipeline writes (camelCase keys). */
+interface MediaVariantRecord {
+  fileType?: string | null;
+  objectKey?: string | null;
+  variantLabel?: string | null;
+}
+
+/**
+ * Choose which stored rendition of this media row to hand the vision model.
+ *
+ * `media.object_key` points at an AVIF derivative — that is what the pipeline produces and
+ * what the site renders, because AVIF is small. It is the wrong thing to send to a vision
+ * API: the mainstream image-understanding endpoints accept JPEG, PNG, GIF and WebP, and
+ * simply reject AVIF. So the mid-size derivatives (`medium_avif`, `large_avif`), which
+ * would otherwise be the ideal choice on download size, are unusable for this call.
+ *
+ * That leaves the `original_uploaded` variant: the untouched file the operator actually
+ * uploaded, in whatever format their camera or design tool produced. The tradeoff is real
+ * and worth naming — it can be several megabytes where a mid-size AVIF would have been a
+ * few dozen kilobytes, so this call is heavier than it looks. It is accepted here because
+ * a heavy call that works beats a cheap one that returns "unsupported image format", and
+ * because alt text is generated once per asset, by hand, not on a hot path.
+ *
+ * When no original was kept (the seeded default assets have no variants) we fall back to
+ * the preview URL the form already computed, and let the route decide.
+ */
+function pickAltTextSourceObjectKey(media: Media): string | null {
+  // `variants` is typed as the generic `Json`, so the cast goes through `unknown`: the
+  // shape is a runtime contract with the upload pipeline, not something the generated
+  // Supabase types can express, and every field is re-checked below before it is used.
+  const variants = Array.isArray(media.variants)
+    ? (media.variants as unknown as MediaVariantRecord[])
+    : [];
+
+  const original = variants.find(
+    (variant) =>
+      variant &&
+      typeof variant === 'object' &&
+      variant.variantLabel === ORIGINAL_UPLOAD_VARIANT_LABEL &&
+      typeof variant.objectKey === 'string' &&
+      variant.objectKey.length > 0
+  );
+
+  return original?.objectKey ?? null;
+}
 
 interface MediaEditFormProps {
   mediaItem: Media;
@@ -33,6 +93,12 @@ export default function MediaEditForm({ mediaItem, formAction }: MediaEditFormPr
   const [description, setDescription] = useState(mediaItem.description || "");
   const [formMessage, setFormMessage] = useState<{ type: 'success' | 'error', text: string } | null>(null);
 
+  // Cortex AI is premium; hide the affordance entirely when the package is not activated
+  // rather than letting the operator click into a 403.
+  const isCortexAiActive = useCortexAiActive();
+  const [isGeneratingAltText, setIsGeneratingAltText] = useState(false);
+  const [altTextError, setAltTextError] = useState<string | null>(null);
+
   useEffect(() => {
     const successMessage = searchParams.get('success');
     const errorMessage = searchParams.get('error');
@@ -78,6 +144,86 @@ export default function MediaEditForm({ mediaItem, formAction }: MediaEditFormPr
   const formRef = React.useRef<HTMLFormElement>(null);
   useHotkeys('ctrl+s', () => formRef.current?.requestSubmit());
   const previewUrl = resolveMediaUrl(mediaItem.file_path || mediaItem.object_key);
+  const isImage = Boolean(mediaItem.file_type?.startsWith("image/"));
+
+  /**
+   * Draft this asset's alt text with Cortex AI.
+   *
+   * `media.description` IS the alt text in this schema — there is no `alt_text` column, and
+   * every consumer (the image block, the feature-image renderer, the media picker) already
+   * reads `description` as alt. So the generated string is written into the existing
+   * `description` state and nothing else changes: persistence still runs through the same
+   * `updateMediaItem(mediaId, { description })` submit path as a hand-typed value, and the
+   * operator still has to press Save. Generating is a draft, not a write.
+   *
+   * The URL handed to the route must be absolute http(s), because the route does not
+   * receive image bytes — it receives a URL the AI SDK then downloads server-side.
+   * `resolveMediaUrl()` returns a relative `/${objectKey}` whenever `NEXT_PUBLIC_R2_BASE_URL`
+   * is unset, which is the default for the native Supabase-storage backend, so on a stock
+   * install every asset would fail this call without the origin fix-up below.
+   */
+  const handleGenerateAltText = async () => {
+    if (!isImage || isGeneratingAltText) {
+      return;
+    }
+
+    const sourceObjectKey = pickAltTextSourceObjectKey(mediaItem);
+    const imageUrl = toAbsoluteImageUrl(
+      sourceObjectKey ? resolveMediaUrl(sourceObjectKey) : previewUrl
+    );
+
+    if (!imageUrl) {
+      setAltTextError(UNRESOLVABLE_IMAGE_URL_MESSAGE);
+      return;
+    }
+
+    setAltTextError(null);
+    setIsGeneratingAltText(true);
+
+    try {
+      // The filename is the only context this screen has, and it is often genuinely
+      // informative ("2026-harvest-crew.jpg"); passing it costs nothing and sometimes
+      // rescues a description that would otherwise be generically correct and useless.
+      const context = buildAltTextContext(
+        `Media library asset named “${mediaItem.file_name}”.`
+      );
+
+      const response = await fetch('/api/ai/seo/alt-text', {
+        // The route's body schema is a `z.strictObject` of optionals, so an absent field
+        // must be omitted rather than sent as null — a null would fail validation outright.
+        body: JSON.stringify({
+          ...(context ? { context } : {}),
+          imageUrl,
+        }),
+        headers: buildCortexAiRequestHeaders(),
+        method: 'POST',
+      });
+
+      const payload = (await response.json().catch(() => null)) as Record<string, unknown> | null;
+
+      if (!response.ok || !payload) {
+        const message =
+          payload && typeof payload['error'] === 'string'
+            ? (payload['error'] as string)
+            : 'Cortex AI could not describe this image.';
+        throw new Error(message);
+      }
+
+      const generated = typeof payload['altText'] === 'string' ? payload['altText'].trim() : '';
+      if (!generated) {
+        throw new Error('Cortex AI returned an empty description.');
+      }
+
+      setDescription(generated);
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : 'Cortex AI could not describe this image.';
+      setAltTextError(message);
+      toast.error(message);
+    } finally {
+      setIsGeneratingAltText(false);
+    }
+  };
 
   return (
     <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
@@ -125,7 +271,29 @@ export default function MediaEditForm({ mediaItem, formAction }: MediaEditFormPr
         </div>
 
         <div>
-          <Label htmlFor="description">Description (Alt Text for Images)</Label>
+          <div className="flex items-center justify-between gap-2">
+            <Label htmlFor="description">Description (Alt Text for Images)</Label>
+            {/* Only for images, and only on a premium install: a non-activated Cortex AI
+                must never render a button that cannot do anything. */}
+            {isCortexAiActive && isImage && (
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                className="h-7 gap-1.5 px-2 text-[11px]"
+                onClick={handleGenerateAltText}
+                disabled={isGeneratingAltText}
+                title="Describe this image with Cortex AI"
+              >
+                {isGeneratingAltText ? (
+                  <Loader2 aria-hidden="true" className="h-3.5 w-3.5 animate-spin" />
+                ) : (
+                  <Sparkles aria-hidden="true" className="h-3.5 w-3.5 text-amber-500" />
+                )}
+                {isGeneratingAltText ? "Generating…" : "Generate with AI"}
+              </Button>
+            )}
+          </div>
           <Textarea
             id="description"
             name="description"
@@ -135,6 +303,13 @@ export default function MediaEditForm({ mediaItem, formAction }: MediaEditFormPr
             rows={4}
             placeholder="e.g., A vibrant sunset over a mountain range"
           />
+          {altTextError && <p className="text-xs text-red-500 mt-1">{altTextError}</p>}
+          {isCortexAiActive && isImage && (
+            <p className="text-xs text-muted-foreground mt-1">
+              Generated text lands in this field as a draft — review it, then press
+              “Update Media Info” to save.
+            </p>
+          )}
         </div>
 
         <div className="flex justify-end space-x-3 pt-4">

package/templates/nextblock-template/app/cms/pages/[id]/edit/EditPageClient.tsx

@@ -14,6 +14,8 @@ import CopyContentFromLanguage from "../../../components/CopyContentFromLanguage
 import RevisionHistoryButton from "../../../revisions/RevisionHistoryButton";
 import { UploadFolderProvider } from '../../../media/UploadFolderContext';
 import { CortexAiPageContextRegistrar } from "../../../components/CortexAiPageContext";
+import { PageSeoAuditSection } from "../../../../../components/seo/PageSeoAuditSection";
+import { PageSeoProvider } from "../../../../../lib/seo/page-audit-context";
 import type { Database } from "@nextblock-cms/db";
 import DraftStatusActions from "../../../components/DraftStatusActions";
 
@@ -76,6 +78,20 @@ export default function EditPageClient({
           translationGroupId: page.translation_group_id,
         }}
       />
+      {/*
+        The provider has to enclose both `PageForm` and `BlockEditorArea`,
+        because the page-level SEO audit is assembled from halves they each own:
+        the form publishes the meta title and description, the block editor
+        publishes the live block array, and neither knows the other exists. It is
+        seeded from the server-rendered row so the panel has a real document to
+        grade on first paint rather than an empty one that scores zero until the
+        block editor finishes mounting.
+      */}
+      <PageSeoProvider
+        initialBlocks={page.blocks}
+        initialMetaDescription={page.meta_description}
+        initialMetaTitle={page.meta_title}
+      >
       <div className="space-y-8 w-full mx-auto px-6">
         <div className="flex justify-between items-center flex-wrap gap-4 w-full">
           <div className="flex items-center gap-3">
@@ -151,6 +167,9 @@ export default function EditPageClient({
         <PageForm
           page={page}
           formAction={updatePageAction}
+        // Read-only: the form never writes blocks, it only lets Cortex AI read them so it
+        // can summarize the page when drafting meta title and description.
+        contentBlocks={page.blocks}
         actionButtonText="Update Page Metadata"
         isEditing={true}
         availableLanguagesProp={allSiteLanguages}
@@ -158,6 +177,14 @@ export default function EditPageClient({
         initialFeatureImageId={initialFeatureImageId}
       />
 
+        {/*
+          Sits between the metadata form and the blocks because that is what it
+          grades: everything above it and everything below it, together. It
+          collapses to a single summary row so the block editor keeps its place
+          on the screen.
+        */}
+        <PageSeoAuditSection />
+
         <Separator className="my-8" />
 
         <div className="w-full mx-auto px-6">
@@ -170,6 +197,7 @@ export default function EditPageClient({
           />
         </div>
       </div>
+      </PageSeoProvider>
     </UploadFolderProvider>
   );
 }