@morphika/andami 0.6.0 → 0.8.1

package/components/seo/JsonLd.tsx

@@ -0,0 +1,50 @@
+/**
+ * JsonLd — Inject one or more JSON-LD structured-data objects as
+ * <script type="application/ld+json"> tags.
+ *
+ * Accepts either a single object or an array. Null/undefined entries are
+ * filtered out, so callers can pass build results directly:
+ *
+ *   <JsonLd data={[
+ *     buildOrganizationJsonLd({ ... }),
+ *     buildWebSiteJsonLd({ ... }),
+ *   ]} />
+ *
+ * Server-rendered safely — uses `dangerouslySetInnerHTML` with a
+ * JSON.stringify that guards against XSS via `</script>` injection.
+ */
+
+type LdRecord = Record<string, unknown>;
+
+interface JsonLdProps {
+  data: LdRecord | null | undefined | Array<LdRecord | null | undefined>;
+}
+
+/**
+ * Escape `</` sequences inside JSON to prevent breaking out of the
+ * <script> tag. Standard hardening per OWASP recommendation.
+ */
+function safeStringify(obj: LdRecord): string {
+  return JSON.stringify(obj).replace(/<\/(script)/gi, "<\\/$1");
+}
+
+export default function JsonLd({ data }: JsonLdProps) {
+  const items = (Array.isArray(data) ? data : [data]).filter(
+    (item): item is LdRecord => item != null && typeof item === "object"
+  );
+
+  if (items.length === 0) return null;
+
+  return (
+    <>
+      {items.map((item, i) => (
+        <script
+          key={i}
+          type="application/ld+json"
+          // eslint-disable-next-line react/no-danger
+          dangerouslySetInnerHTML={{ __html: safeStringify(item) }}
+        />
+      ))}
+    </>
+  );
+}

package/components/seo/ProjectJsonLd.tsx

@@ -0,0 +1,44 @@
+/**
+ * ProjectJsonLd — Server component that emits a `CreativeWork` JSON-LD
+ * record for a project page (`/work/[slug]`). Rendered inline at the top
+ * of the project page so search engines see the structured data alongside
+ * the HTML body.
+ *
+ * Falls back to siteSettings.default_author for the author field when the
+ * page doesn't specify one. Returns null when the page has insufficient
+ * data — search engines tolerate partial schemas, but emitting an empty
+ * CreativeWork would be noise.
+ */
+
+import JsonLd from "./JsonLd";
+import { buildCreativeWorkJsonLd } from "../../lib/seo/jsonld";
+import { getCachedSiteSettings, toAbsoluteUrl } from "../../lib/seo/site-settings";
+import { getSiteConfig } from "../../lib/config";
+import { assetUrl } from "../../lib/assets";
+import type { Page } from "../../lib/sanity/types";
+
+interface ProjectJsonLdProps {
+  page: Page;
+}
+
+export default async function ProjectJsonLd({ page }: ProjectJsonLdProps) {
+  const settings = await getCachedSiteSettings();
+  const cfg = getSiteConfig();
+
+  const url = `${cfg.domain.replace(/\/$/, "")}/work/${page.slug?.current || ""}`;
+  const imageAbsolute = page.thumbnail_path
+    ? toAbsoluteUrl(assetUrl(page.thumbnail_path), cfg.domain)
+    : undefined;
+  const authorName = settings?.default_author || cfg.name;
+
+  const ld = buildCreativeWorkJsonLd({
+    name: page.title,
+    url,
+    image: imageAbsolute,
+    datePublished: page.published_at,
+    description: page.metadata?.seo_description,
+    authorName,
+  });
+
+  return <JsonLd data={ld} />;
+}

package/components/seo/SiteSeoHead.tsx

@@ -0,0 +1,66 @@
+/**
+ * SiteSeoHead — Server component that emits site-wide SEO surfaces:
+ *
+ *   - JSON-LD `Organization` (logo + sameAs profiles → Google Knowledge Panel)
+ *   - JSON-LD `WebSite` (basic site identity)
+ *   - `<meta name="google-site-verification">` (when configured)
+ *   - `<meta name="msvalidate.01">` for Bing Webmaster (when configured)
+ *
+ * Rendered inside the public site layout so every public page emits these.
+ * Admin and Studio routes are excluded (different layout subtree).
+ *
+ * Data source: siteSettings document in Sanity (cached via React `cache()`).
+ * Empty fields are omitted — partial schemas are tolerated by search engines.
+ */
+
+import JsonLd from "./JsonLd";
+import { buildOrganizationJsonLd, buildWebSiteJsonLd } from "../../lib/seo/jsonld";
+import { getCachedSiteSettings, toAbsoluteUrl } from "../../lib/seo/site-settings";
+import { getSiteConfig } from "../../lib/config";
+import { assetUrl } from "../../lib/assets";
+
+export default async function SiteSeoHead() {
+  const settings = await getCachedSiteSettings();
+  const cfg = getSiteConfig();
+
+  const logoAbsolute = settings?.org_logo
+    ? toAbsoluteUrl(assetUrl(settings.org_logo), cfg.domain)
+    : undefined;
+
+  const description =
+    settings?.default_description || cfg.defaults.metaDescription || undefined;
+
+  const orgLd = buildOrganizationJsonLd({
+    name: cfg.name,
+    url: cfg.domain,
+    logo: logoAbsolute,
+    socialLinks: settings?.social_links,
+    description,
+    foundingYear: settings?.founding_year,
+    addressLocality: settings?.address_locality,
+    addressCountry: settings?.address_country,
+    contactEmail: settings?.contact_email,
+    keywords: settings?.keywords,
+  });
+
+  const siteLd = buildWebSiteJsonLd({
+    name: cfg.name,
+    url: cfg.domain,
+    description,
+  });
+
+  return (
+    <>
+      <JsonLd data={[orgLd, siteLd]} />
+      {settings?.verification_google && (
+        <meta
+          name="google-site-verification"
+          content={settings.verification_google}
+        />
+      )}
+      {settings?.verification_bing && (
+        <meta name="msvalidate.01" content={settings.verification_bing} />
+      )}
+    </>
+  );
+}

package/lib/sanity/queries.ts

@@ -227,12 +227,15 @@ export const allPageSlugsQuery = groq`
   *[_type == "page" && page_type != "project" && draft_mode != true && defined(slug.current)].slug.current
 `;
 
-// All non-project pages for sitemap.xml — includes _updatedAt for accurate <lastmod>
-// and respects metadata.noindex to exclude hidden pages from the sitemap.
+// All non-project pages for sitemap.xml + llms.txt — includes _updatedAt for
+// accurate <lastmod>, plus title and description for llms.txt entries.
+// Respects metadata.noindex to exclude hidden pages.
 export const allPagesForSitemapQuery = groq`
-  *[_type == "page" && page_type != "project" && draft_mode != true && defined(slug.current) && metadata.noindex != true] {
+  *[_type == "page" && page_type != "project" && draft_mode != true && defined(slug.current) && metadata.noindex != true] | order(is_home desc, title asc) {
     "slug": slug.current,
-    "updatedAt": _updatedAt
+    "updatedAt": _updatedAt,
+    title,
+    "description": metadata.seo_description
   }
 `;
 
@@ -258,12 +261,16 @@ export const allProjectSlugsQuery = groq`
   *[_type == "page" && page_type == "project" && draft_mode != true && defined(slug.current)].slug.current
 `;
 
-// All published projects for sitemap.xml — includes _updatedAt for accurate <lastmod>
-// and respects metadata.noindex to exclude hidden projects from the sitemap.
+// All published projects for sitemap.xml — includes _updatedAt for accurate <lastmod>,
+// thumbnail_path for image sitemap, and respects metadata.noindex.
 export const allProjectsForSitemapQuery = groq`
   *[_type == "page" && page_type == "project" && draft_mode != true && defined(slug.current) && metadata.noindex != true] {
     "slug": slug.current,
-    "updatedAt": _updatedAt
+    "updatedAt": _updatedAt,
+    thumbnail_path,
+    title,
+    "description": metadata.seo_description,
+    published_at
   }
 `;
 
@@ -440,6 +447,16 @@ export const siteSettingsQuery = groq`
     default_og_image,
     favicon_path,
     analytics_id,
+    org_logo,
+    default_author,
+    social_links,
+    founding_year,
+    address_locality,
+    address_country,
+    contact_email,
+    keywords,
+    verification_google,
+    verification_bing,
     seed_url,
     last_scanned_at,
     asset_status

package/lib/sanity/types.ts

@@ -1031,6 +1031,14 @@ export interface AssetRegistry {
 // Site Settings
 // ============================================
 
+export interface SocialLink {
+  _key?: string;
+  /** Optional display label (e.g. "Instagram", "Behance"). For admin organization only. */
+  label?: string;
+  /** Profile URL — emitted as schema.org sameAs[]. */
+  url: string;
+}
+
 export interface SiteSettings {
   nav_items?: NavItem[];
   nav_design?: NavDesign;
@@ -1040,6 +1048,26 @@ export interface SiteSettings {
   default_og_image?: string;
   favicon_path?: string;
   analytics_id?: string;
+  /** Asset path to the organization logo used by JSON-LD `Organization.logo`. */
+  org_logo?: string;
+  /** Default author for project pages (used in `CreativeWork.author` when not overridden). */
+  default_author?: string;
+  /** Social profile URLs emitted as schema.org `sameAs[]`. */
+  social_links?: SocialLink[];
+  /** Year the organization was founded. Emitted as schema.org `foundingDate`. */
+  founding_year?: number;
+  /** City/town (schema.org `address.addressLocality`). */
+  address_locality?: string;
+  /** Country name or ISO code (schema.org `address.addressCountry`). */
+  address_country?: string;
+  /** Public contact email (schema.org `contactPoint.email`). */
+  contact_email?: string;
+  /** Areas of expertise — short tags emitted as schema.org `knowsAbout[]`. */
+  keywords?: string[];
+  /** Google Search Console verification code (HTML tag method). */
+  verification_google?: string;
+  /** Bing Webmaster Tools verification code. */
+  verification_bing?: string;
   seed_url?: string;
   last_scanned_at?: string;
   asset_status?: "ok" | "scanning" | "error";

package/lib/seo/jsonld.ts

@@ -0,0 +1,174 @@
+/**
+ * JSON-LD structured data builders for schema.org types.
+ *
+ * Pure functions — each takes input data and returns a plain JSON-LD object
+ * ready to be serialized into a <script type="application/ld+json"> tag.
+ *
+ * Empty/missing fields are simply omitted from the output (search engines
+ * tolerate partial schemas). All builders return `null` when the minimum
+ * required fields aren't present, so callers can skip emission entirely.
+ *
+ * Schema reference: https://schema.org/
+ * Google guidance: https://developers.google.com/search/docs/appearance/structured-data
+ */
+
+import type { SocialLink } from "../sanity/types";
+
+// ============================================
+// Types
+// ============================================
+
+export interface OrganizationInput {
+  name: string;
+  url: string;
+  /** Absolute URL to the organization logo (NOT a relative asset path). */
+  logo?: string;
+  /** Profile URLs (filtered & trimmed). */
+  socialLinks?: SocialLink[];
+  /** Optional descriptive tagline for the organization. */
+  description?: string;
+  /** Year the org was founded (emitted as ISO date `YYYY`). */
+  foundingYear?: number;
+  /** City/town of the org's primary address. */
+  addressLocality?: string;
+  /** Country name or ISO code. */
+  addressCountry?: string;
+  /** Public contact email (creates a `contactPoint`). */
+  contactEmail?: string;
+  /** Tags / areas of expertise emitted as `knowsAbout[]`. */
+  keywords?: string[];
+}
+
+export interface WebSiteInput {
+  name: string;
+  url: string;
+  description?: string;
+}
+
+export interface CreativeWorkInput {
+  /** Title of the work. */
+  name: string;
+  /** Absolute URL of the work's page. */
+  url: string;
+  /** Absolute URL to the work's primary image (thumbnail / hero). */
+  image?: string;
+  /** ISO 8601 publication date. */
+  datePublished?: string;
+  /** Short descriptive text. */
+  description?: string;
+  /** Name of the creating organization or person (falls back to org name). */
+  authorName?: string;
+}
+
+// ============================================
+// Builders
+// ============================================
+
+/**
+ * Organization — emitted site-wide. Powers Google Knowledge Panel for brand
+ * searches when combined with verified profiles via `sameAs`.
+ */
+export function buildOrganizationJsonLd(
+  input: OrganizationInput
+): Record<string, unknown> | null {
+  if (!input.name || !input.url) return null;
+
+  const ld: Record<string, unknown> = {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    name: input.name,
+    url: input.url,
+  };
+
+  if (input.logo) ld.logo = input.logo;
+  if (input.description) ld.description = input.description;
+
+  // foundingDate — schema.org expects ISO date; year-only is valid per spec
+  if (input.foundingYear && Number.isFinite(input.foundingYear)) {
+    ld.foundingDate = String(Math.round(input.foundingYear));
+  }
+
+  // Address — PostalAddress with locality/country
+  if (input.addressLocality || input.addressCountry) {
+    const address: Record<string, unknown> = {
+      "@type": "PostalAddress",
+    };
+    if (input.addressLocality) address.addressLocality = input.addressLocality;
+    if (input.addressCountry) address.addressCountry = input.addressCountry;
+    ld.address = address;
+  }
+
+  // ContactPoint — only emit if email present (schema.org requires contactType)
+  if (input.contactEmail) {
+    ld.contactPoint = {
+      "@type": "ContactPoint",
+      contactType: "customer service",
+      email: input.contactEmail,
+    };
+  }
+
+  // knowsAbout — array of strings (or schema.org Things)
+  const knowsAbout = (input.keywords || [])
+    .map((k) => k?.trim())
+    .filter((k): k is string => Boolean(k));
+  if (knowsAbout.length > 0) ld.knowsAbout = knowsAbout;
+
+  // sameAs — social profile URLs
+  const sameAs = (input.socialLinks || [])
+    .map((l) => l?.url?.trim())
+    .filter((u): u is string => Boolean(u));
+  if (sameAs.length > 0) ld.sameAs = sameAs;
+
+  return ld;
+}
+
+/**
+ * WebSite — emitted site-wide. Helps Google identify the site as a coherent
+ * web property (separate from individual pages).
+ */
+export function buildWebSiteJsonLd(
+  input: WebSiteInput
+): Record<string, unknown> | null {
+  if (!input.name || !input.url) return null;
+
+  const ld: Record<string, unknown> = {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    name: input.name,
+    url: input.url,
+  };
+
+  if (input.description) ld.description = input.description;
+
+  return ld;
+}
+
+/**
+ * CreativeWork — emitted on project pages. Tells Google the page represents a
+ * specific creative work (motion graphic, illustration, photograph, etc.) and
+ * unlocks richer result presentation.
+ */
+export function buildCreativeWorkJsonLd(
+  input: CreativeWorkInput
+): Record<string, unknown> | null {
+  if (!input.name || !input.url) return null;
+
+  const ld: Record<string, unknown> = {
+    "@context": "https://schema.org",
+    "@type": "CreativeWork",
+    name: input.name,
+    url: input.url,
+  };
+
+  if (input.image) ld.image = input.image;
+  if (input.datePublished) ld.datePublished = input.datePublished;
+  if (input.description) ld.description = input.description;
+  if (input.authorName) {
+    ld.author = {
+      "@type": "Organization",
+      name: input.authorName,
+    };
+  }
+
+  return ld;
+}

package/lib/seo/site-settings.ts

@@ -0,0 +1,37 @@
+/**
+ * Cached siteSettings fetch — shared between (site)/layout.tsx and the
+ * SEO server components (SiteSeoHead, ProjectJsonLd).
+ *
+ * React's `cache()` deduplicates within a single render pass: layout and
+ * SEO components called from the same route render share one Sanity fetch.
+ * The underlying `client` already uses Sanity's CDN (2ms vs 200ms), so
+ * cold fetches are cheap anyway.
+ */
+
+import { cache } from "react";
+import { client } from "../sanity/client";
+import { siteSettingsQuery } from "../sanity/queries";
+import type { SiteSettings } from "../sanity/types";
+
+export const getCachedSiteSettings = cache(async (): Promise<SiteSettings | null> => {
+  try {
+    return await client.fetch<SiteSettings>(siteSettingsQuery);
+  } catch (error) {
+    console.error("[SEO] Failed to fetch site settings:", error);
+    return null;
+  }
+});
+
+/**
+ * Coerce any asset URL (relative path, /api proxy, or full CDN URL) to an
+ * absolute URL using the configured site domain as base. Required by
+ * schema.org — JSON-LD URLs must be fully qualified.
+ */
+export function toAbsoluteUrl(url: string | undefined, base: string): string | undefined {
+  if (!url) return undefined;
+  try {
+    return new URL(url, base).toString();
+  } catch {
+    return undefined;
+  }
+}

package/lib/version.ts

@@ -6,4 +6,4 @@
  * Exposed as a plain constant so it can be imported without reading
  * package.json at runtime.
  */
-export const ANDAMI_VERSION = "0.6.0";
+export const ANDAMI_VERSION = "0.8.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morphika/andami",
-  "version": "0.6.0",
+  "version": "0.8.1",
   "description": "Visual Page Builder — core library. A reusable website builder with visual editing, CMS integration, and asset management.",
   "type": "module",
   "license": "MIT",
@@ -128,6 +128,7 @@
     "./site/error": "./site/error.ts",
     "./site/robots": "./site/robots.ts",
     "./site/sitemap": "./site/sitemap.ts",
+    "./site/llms-txt": "./site/llms-txt.ts",
     "./admin": "./admin/index.ts",
     "./admin/login": "./admin/login.ts",
     "./admin/pages": "./admin/pages.ts",

package/sanity/schemas/siteSettings.ts

@@ -11,6 +11,9 @@ export default defineType({
     { name: "nav", title: "Navigation", default: true },
     { name: "nav_design", title: "Nav Design" },
     { name: "meta", title: "Metadata" },
+    { name: "social", title: "Social & Branding" },
+    { name: "organization", title: "Organization Info" },
+    { name: "verification", title: "Search Verification" },
     { name: "assets", title: "Assets" },
   ],
   fields: [
@@ -296,6 +299,105 @@ export default defineType({
     defineField({ name: "favicon_path", title: "Favicon Path", type: "string", group: "meta" }),
     defineField({ name: "analytics_id", title: "Analytics ID", type: "string", group: "meta" }),
 
+    // === SOCIAL & BRANDING (used by JSON-LD structured data) ===
+    defineField({
+      name: "org_logo",
+      title: "Organization Logo",
+      type: "string",
+      group: "social",
+      description: "Asset path to the logo used by Google's Knowledge Panel and rich results. Square images recommended (min 112×112, ideal 500×500).",
+    }),
+    defineField({
+      name: "default_author",
+      title: "Default Author",
+      type: "string",
+      group: "social",
+      description: "Used as the author of project pages when not overridden. Typically your studio/agency name.",
+    }),
+    defineField({
+      name: "social_links",
+      title: "Social Profiles",
+      type: "array",
+      group: "social",
+      description: "Profile URLs (Instagram, LinkedIn, Behance, Vimeo, etc.) emitted as schema.org sameAs[] so Google links your organization to its social presence.",
+      of: [
+        {
+          type: "object",
+          fields: [
+            defineField({ name: "label", title: "Label", type: "string", description: "Optional display name (e.g. Instagram, Behance). For admin organization only." }),
+            defineField({ name: "url", title: "URL", type: "url", validation: (Rule) => Rule.required().uri({ scheme: ["http", "https"] }) }),
+          ],
+          preview: {
+            select: { label: "label", url: "url" },
+            prepare({ label, url }: { label?: string; url?: string }) {
+              return {
+                title: label || url || "(empty)",
+                subtitle: label ? url : undefined,
+              };
+            },
+          },
+        },
+      ],
+    }),
+
+    // === ORGANIZATION INFO (citation-friendly facts for LLMs + JSON-LD) ===
+    defineField({
+      name: "founding_year",
+      title: "Founded (year)",
+      type: "number",
+      group: "organization",
+      description: "Year your organization was founded. Cited by AI agents answering 'when was X founded'. Emitted as schema.org foundingDate.",
+      validation: (Rule) => Rule.min(1800).max(new Date().getFullYear()),
+    }),
+    defineField({
+      name: "address_locality",
+      title: "City",
+      type: "string",
+      group: "organization",
+      description: "City or town where your organization is based (e.g. 'Barcelona', 'Berlin'). Emitted as schema.org address.addressLocality.",
+    }),
+    defineField({
+      name: "address_country",
+      title: "Country",
+      type: "string",
+      group: "organization",
+      description: "Country name or ISO code (e.g. 'Spain', 'ES'). Emitted as schema.org address.addressCountry.",
+    }),
+    defineField({
+      name: "contact_email",
+      title: "Contact Email",
+      type: "string",
+      group: "organization",
+      description: "Public contact email. Emitted as schema.org contactPoint.email.",
+      validation: (Rule) => Rule.email().error("Must be a valid email address"),
+    }),
+    defineField({
+      name: "keywords",
+      title: "Areas of Expertise",
+      type: "array",
+      group: "organization",
+      description: "Short list of services / specialties (e.g. 'CGI', 'Motion Graphics', '3D Animation'). Emitted as schema.org knowsAbout — helps LLMs cite you for related queries.",
+      of: [{ type: "string" }],
+      options: { layout: "tags" },
+      validation: (Rule) => Rule.max(20),
+    }),
+
+    // === SEARCH ENGINE VERIFICATION ===
+    defineField({
+      name: "verification_google",
+      title: "Google Search Console",
+      type: "string",
+      group: "verification",
+      description: "The content value from Google Search Console's HTML tag verification method. Just the code, not the full <meta> tag.",
+    }),
+    defineField({
+      name: "verification_bing",
+      title: "Bing Webmaster",
+      type: "string",
+      group: "verification",
+      description: "The content value from Bing Webmaster Tools' HTML tag verification. Just the code.",
+    }),
+
     // === SETUP ===
     defineField({
       name: "setup_complete",

package/site/llms-txt.ts

@@ -0,0 +1,10 @@
+/**
+ * @morphika/andami/site/llms-txt — AI/LLM-friendly site summary route.
+ *
+ * Re-exports the framework's /llms.txt route handler so instances can mount
+ * it at `/llms.txt`. Required instance setup (one-time, see CHANGELOG):
+ *
+ *   // app/llms.txt/route.ts (in your instance repo)
+ *   export { GET, revalidate } from "@morphika/andami/site/llms-txt";
+ */
+export { GET, revalidate } from "../app/llms.txt/route";