@gradial/aci 0.1.46 → 0.1.48

package/templates/astro/template/src/aci/error-page-instrumentation.mjs

@@ -0,0 +1,33 @@
+// Error-page analytics policy — THIS FILE IS YOURS (customer-owned;
+// code-organization R-14 / authorable-error-pages D-15). The ACI SDK owns
+// the delivery mechanism (when this runs, serialization, the
+// data-aci-error-page marker); this file owns WHAT is pushed.
+//
+// Contract:
+// - pushErrorPageView MUST stay self-contained: browser globals only — no
+//   imports, no closed-over identifiers. The Astro seats and the 500.html
+//   emitter execute it STRINGIFIED via toString(), so anything outside the
+//   function body is lost.
+// - Emptying the body to a no-op disables error-page analytics on every
+//   surface (404.astro, 500.astro, emitted static copies) — the sanctioned
+//   alternative to GTM-container-side suppression.
+// - Plain .mjs on purpose: it is consumed verbatim, never transpiled.
+
+/**
+ * Pushes one `page_view` event per error-surface view (D-14 default
+ * payload). `page_path` is the visitor's requested path, so 404 reports
+ * double as a broken-link inventory.
+ *
+ * @param {'not_found' | 'error'} pageType
+ */
+export function pushErrorPageView(pageType) {
+  window.dataLayer = window.dataLayer || [];
+  window.dataLayer.push({
+    event: 'page_view',
+    page_type: pageType,
+    page_path: window.location.pathname,
+    page_location: window.location.href,
+    page_referrer: document.referrer || '(direct)',
+    page_title: document.title,
+  });
+}

package/templates/astro/template/src/pages/404.astro

@@ -0,0 +1,54 @@
+---
+// Astro's native notFound error seat (authorable-error-pages REQ-7).
+// Renders the page bound by site.json#errorPages.notFound through the normal
+// SiteLayout path; static builds emit dist/404.html, which doubles as the
+// direct /404/ route and the error surface (D-11 — the instrumentation on a
+// direct visit is the accepted consequence). If the bound page cannot be
+// loaded, the SDK degrades to its shipped default fragment — this seat never
+// throws.
+import { getErrorPageData, createRenderChildren } from '@gradial/aci/astro';
+import { registry } from '../cms/registry';
+import SiteLayout from '../layouts/SiteLayout.astro';
+import { pushErrorPageView } from '../aci/error-page-instrumentation.mjs';
+
+const errorPage = await getErrorPageData(Astro, 'notFound', { pushErrorPageView });
+const data = errorPage.data;
+const renderChildren = createRenderChildren(registry);
+---
+
+<SiteLayout
+  title={errorPage.meta.title}
+  description={errorPage.meta.description}
+  canonical={errorPage.meta.canonical}
+  siteName={errorPage.meta.siteName}
+>
+  {data ? (
+    data.layout.slots.map((slot) => {
+      const blocks = data.slots[slot.name];
+      if (!blocks?.length) return null;
+      const rendered = renderChildren(blocks);
+      if (slot.name === 'main') {
+        return (
+          <main id="content-main">
+            {rendered.map((child) => {
+              const Comp = child.Component as any;
+              return Comp ? <Comp {...child.props} /> : null;
+            })}
+          </main>
+        );
+      }
+      return rendered.map((child) => {
+        const Comp = child.Component as any;
+        return Comp ? <Comp {...child.props} /> : null;
+      });
+    })
+  ) : (
+    <Fragment set:html={errorPage.fallbackHtml} />
+  )}
+  <!-- D-14 error-surface analytics: ONE page_view push with the visitor's
+       requested path. The push body is site-owned (D-15): the SDK serializes
+       src/aci/error-page-instrumentation.mjs into this tag, injected like
+       SiteLayout's collectTag; inline scripts execute here — Astro serves
+       real HTML documents (unlike the Next flight-rendered seat). -->
+  <Fragment set:html={errorPage.instrumentationTag} />
+</SiteLayout>

package/templates/astro/template/src/pages/500.astro

@@ -0,0 +1,53 @@
+---
+// Astro's native catchAll (500) error seat (authorable-error-pages REQ-7).
+// Renders the page bound by site.json#errorPages.catchAll through the normal
+// SiteLayout path. Static builds emit dist/500.html for the hosting layer;
+// server output serves this seat when a route throws during on-demand
+// rendering. If the bound page cannot be loaded, the SDK degrades to its
+// shipped default fragment — this seat never throws.
+import { getErrorPageData, createRenderChildren } from '@gradial/aci/astro';
+import { registry } from '../cms/registry';
+import SiteLayout from '../layouts/SiteLayout.astro';
+import { pushErrorPageView } from '../aci/error-page-instrumentation.mjs';
+
+const errorPage = await getErrorPageData(Astro, 'catchAll', { pushErrorPageView });
+const data = errorPage.data;
+const renderChildren = createRenderChildren(registry);
+---
+
+<SiteLayout
+  title={errorPage.meta.title}
+  description={errorPage.meta.description}
+  canonical={errorPage.meta.canonical}
+  siteName={errorPage.meta.siteName}
+>
+  {data ? (
+    data.layout.slots.map((slot) => {
+      const blocks = data.slots[slot.name];
+      if (!blocks?.length) return null;
+      const rendered = renderChildren(blocks);
+      if (slot.name === 'main') {
+        return (
+          <main id="content-main">
+            {rendered.map((child) => {
+              const Comp = child.Component as any;
+              return Comp ? <Comp {...child.props} /> : null;
+            })}
+          </main>
+        );
+      }
+      return rendered.map((child) => {
+        const Comp = child.Component as any;
+        return Comp ? <Comp {...child.props} /> : null;
+      });
+    })
+  ) : (
+    <Fragment set:html={errorPage.fallbackHtml} />
+  )}
+  <!-- D-14 error-surface analytics: ONE page_view push with the visitor's
+       requested path. The push body is site-owned (D-15): the SDK serializes
+       src/aci/error-page-instrumentation.mjs into this tag, injected like
+       SiteLayout's collectTag; inline scripts execute here — Astro serves
+       real HTML documents (unlike the Next flight-rendered seat). -->
+  <Fragment set:html={errorPage.instrumentationTag} />
+</SiteLayout>

package/templates/astro/template/src/pages/[...slug].astro

@@ -1,5 +1,5 @@
 ---
-import { getGradialStaticPaths, getPageData, createRenderChildren } from '@gradial/aci/astro';
+import { getGradialStaticPaths, getPageData, createRenderChildren, PageNotFoundError, type PageData } from '@gradial/aci/astro';
 import { registry } from '../cms/registry';
 import SiteLayout from '../layouts/SiteLayout.astro';
 
@@ -7,7 +7,20 @@ export const getStaticPaths = getGradialStaticPaths;
 
 // SDK owns route normalization, content loading, metadata, layout/slot
 // resolution, and collect-tag emission. No FileContentProvider imports.
-const data = await getPageData(Astro);
+//
+// Server output: unknown routes raise PageNotFoundError here; rewrite to the
+// 404 seat so misses answer HTTP 404, not 500 (authorable-error-pages D-10).
+// src/pages/404.astro is load-bearing for this rewrite — deleting it turns
+// every miss into a 500.
+// Static output never takes this branch — getStaticPaths only emits known
+// routes.
+let data: PageData;
+try {
+  data = await getPageData(Astro);
+} catch (error) {
+  if (error instanceof PageNotFoundError) return Astro.rewrite('/404/');
+  throw error;
+}
 const renderChildren = createRenderChildren(registry);
 ---
 

package/templates/common/.agents/skills/authoring/SKILL.md

@@ -238,6 +238,77 @@ Global elements (navigation, footer, branding, SEO) live in
 }
 ```
 
+### Error Pages
+
+Sites bind their error pages in `site.json` via `errorPages`:
+
+```json
+{
+  "errorPages": {
+    "notFound": "/404/",
+    "catchAll": "/error/"
+  }
+}
+```
+
+- Each binding is a route path resolving to an **ordinary content page**
+  (`.content/pages/404/_index.json`, `.content/pages/error/_index.json`) —
+  authored with normal layouts and components like any other page.
+  `notFound` serves unknown routes with HTTP 404; `catchAll` serves
+  application errors (500-class).
+- Error pages stay out of discovery: set `metadata.sitemap.visible: false`
+  on both pages, and the template `robots.txt` disallows both routes.
+- If `errorPages` is absent, the build warns loudly and ships a
+  branded-neutral default page (warn-then-enforce migration: absent
+  bindings will eventually fail the build, so author them). Present but
+  broken bindings — malformed paths, no matching page, unpublished page —
+  fail the build immediately.
+- Error pages are base-audience only: no personalization, audience, or
+  experiment overlays (validation rejects them), and collect/assignment
+  markup is stripped from materialized copies.
+- Analytics: error-surface renders push one `page_view` event to
+  `window.dataLayer` with `page_type` (`not_found` | `error`),
+  `page_path` (the visitor's requested path), `page_location`,
+  `page_referrer`, and `page_title`. The push body is site-owned
+  (`src/aci/error-page-instrumentation.mjs` — see the GTM/GA4 section
+  below); the SDK wrappers handle delivery.
+
+### Error-page analytics (GTM/GA4)
+
+The push body is YOURS: it lives in the site-owned
+`src/aci/error-page-instrumentation.mjs`, whose `pushErrorPageView`
+function every error surface (Next seats, Astro seats, the emitted static
+`500.html`) executes. The scaffolded default pushes one event to
+`window.dataLayer`:
+
+```js
+{ event: 'page_view', page_type: 'not_found' | 'error',
+  page_path, page_location, page_referrer, page_title }
+```
+
+- **Customize** — edit the function in place. It must stay self-contained
+  (browser globals only, no imports, no closed-over identifiers): some
+  surfaces execute it stringified.
+- **Disable** — make the function body a no-op. That turns off error-page
+  analytics on every surface, and no GTM-side suppression is needed.
+
+Container-side dedup is only needed when you KEEP the default push
+alongside automatic GA4 page views: because the event name is `page_view`,
+either disable `send_page_view` and drive all page views from the
+dataLayer, or add a trigger exception on the config tag for error
+surfaces. The stable suppression signal is the `data-aci-error-page`
+attribute (values `not_found` | `error`; the attribute is SDK-owned and
+stable regardless of what your push does): present on the instrumentation
+script tag (Astro, parse-time) and on a server-rendered marker element
+(Next, in the DOM before container load), so container-load triggers can
+gate on it in both frameworks. If you leave automatic page views on and
+also keep the default push, error pages will double-count — that is a
+container configuration choice, not an SDK default.
+
+Direct visits to `/404/` and `/error/` do not carry error context and do
+not push the event (Astro static output is the one exception: its
+`404.html` doubles as the direct route).
+
 ### ID Conventions
 
 - Every block must have a unique `id` within the page.

package/templates/common/.content/config/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+Disallow: /404/
+Disallow: /error/

package/templates/common/.content/config/site.json.tmpl

@@ -6,6 +6,10 @@
   "domain": "localhost",
   "defaultLocale": "en-us",
   "locales": ["en-us"],
+  "errorPages": {
+    "notFound": "/404/",
+    "catchAll": "/error/"
+  },
   "overlayResolution": ["locale"],
   "brandHref": "/",
   "seo": {

package/templates/common/.content/pages/404/_index.json

@@ -0,0 +1,31 @@
+{
+  "$type": "page",
+  "id": "meridian-not-found",
+  "status": "published",
+  "layout": "default",
+  "metadata": {
+    "title": "Page not found — Meridian",
+    "description": "The page you are looking for does not exist.",
+    "sitemap": { "visible": false }
+  },
+  "regions": {
+    "main": [
+      {
+        "id": "not-found-hero",
+        "component": "home_hero",
+        "props": {
+          "eyebrow": "404",
+          "headline": "This page drifted out of orbit.",
+          "description": "The page you are looking for does not exist or has moved. Check the address, or head back to the homepage.",
+          "ctaLabel": "Back to home",
+          "ctaHref": "/",
+          "image": {
+            "$type": "dam.assetRef",
+            "assetId": "ast_site_home_hero",
+            "alt": "Light abstract background with satellite constellation"
+          }
+        }
+      }
+    ]
+  }
+}

package/templates/common/.content/pages/error/_index.json

@@ -0,0 +1,31 @@
+{
+  "$type": "page",
+  "id": "meridian-error",
+  "status": "published",
+  "layout": "default",
+  "metadata": {
+    "title": "Something went wrong — Meridian",
+    "description": "An unexpected error occurred while serving this page.",
+    "sitemap": { "visible": false }
+  },
+  "regions": {
+    "main": [
+      {
+        "id": "error-hero",
+        "component": "home_hero",
+        "props": {
+          "eyebrow": "Temporary interruption",
+          "headline": "Something went wrong on our end.",
+          "description": "An unexpected error occurred while serving this page. Please try again in a moment, or head back to the homepage.",
+          "ctaLabel": "Back to home",
+          "ctaHref": "/",
+          "image": {
+            "$type": "dam.assetRef",
+            "assetId": "ast_site_home_hero",
+            "alt": "Light abstract background with satellite constellation"
+          }
+        }
+      }
+    ]
+  }
+}

package/templates/common/.content/schemas/site.schema.json

@@ -7,6 +7,15 @@
   "additionalProperties": true,
   "properties": {
     "$type": { "const": "site" },
+    "errorPages": {
+      "type": "object",
+      "required": ["notFound", "catchAll"],
+      "additionalProperties": false,
+      "properties": {
+        "notFound": { "type": "string", "pattern": "^/(?:[A-Za-z0-9._~-]+/)+$" },
+        "catchAll": { "type": "string", "pattern": "^/(?:[A-Za-z0-9._~-]+/)+$" }
+      }
+    },
     "id": { "type": "string", "minLength": 1 },
     "status": { "type": "string", "minLength": 1 },
     "title": { "type": "string", "minLength": 1 },

package/templates/common/starter-content/.content/config/robots.txt

@@ -1,2 +1,4 @@
 User-agent: *
 Allow: /
+Disallow: /404/
+Disallow: /error/

package/templates/common/starter-content/.content/config/site.json

@@ -6,6 +6,10 @@
   "domain": "www.meridian.local",
   "defaultLocale": "en-us",
   "locales": ["en-us"],
+  "errorPages": {
+    "notFound": "/404/",
+    "catchAll": "/error/"
+  },
   "overlayResolution": ["locale", "audience"],
   "brandHref": "/",
   "brandLogo": {

package/templates/common/starter-content/.content/pages/404/_index.json

@@ -0,0 +1,31 @@
+{
+  "$type": "page",
+  "id": "meridian-not-found",
+  "status": "published",
+  "layout": "default",
+  "metadata": {
+    "title": "Page not found — Meridian",
+    "description": "The page you are looking for does not exist.",
+    "sitemap": { "visible": false }
+  },
+  "regions": {
+    "main": [
+      {
+        "id": "not-found-hero",
+        "component": "home_hero",
+        "props": {
+          "eyebrow": "404",
+          "headline": "This page drifted out of orbit.",
+          "description": "The page you are looking for does not exist or has moved. Check the address, or head back to the homepage.",
+          "ctaLabel": "Back to home",
+          "ctaHref": "/",
+          "image": {
+            "$type": "dam.assetRef",
+            "assetId": "ast_site_home_hero",
+            "alt": "Light abstract background with satellite constellation"
+          }
+        }
+      }
+    ]
+  }
+}

package/templates/common/starter-content/.content/pages/about/_index.json

@@ -24,8 +24,7 @@
             "assetId": "ast_site_about_hero",
             "alt": "Meridian network coverage map with soft gradient"
           }
-        },
-        "$type": "component"
+        }
       },
       {
         "id": "about-actions",
@@ -42,12 +41,10 @@
                 "variant": "primary",
                 "icon": "arrow_forward",
                 "iconPosition": "after"
-              },
-              "$type": "component"
+              }
             }
           ]
-        },
-        "$type": "component"
+        }
       }
     ]
   }

package/templates/common/starter-content/.content/pages/error/_index.json

@@ -0,0 +1,31 @@
+{
+  "$type": "page",
+  "id": "meridian-error",
+  "status": "published",
+  "layout": "default",
+  "metadata": {
+    "title": "Something went wrong — Meridian",
+    "description": "An unexpected error occurred while serving this page.",
+    "sitemap": { "visible": false }
+  },
+  "regions": {
+    "main": [
+      {
+        "id": "error-hero",
+        "component": "home_hero",
+        "props": {
+          "eyebrow": "Temporary interruption",
+          "headline": "Something went wrong on our end.",
+          "description": "An unexpected error occurred while serving this page. Please try again in a moment, or head back to the homepage.",
+          "ctaLabel": "Back to home",
+          "ctaHref": "/",
+          "image": {
+            "$type": "dam.assetRef",
+            "assetId": "ast_site_home_hero",
+            "alt": "Light abstract background with satellite constellation"
+          }
+        }
+      }
+    ]
+  }
+}

package/templates/common/starter-content/.content/pages/home/_index.json

@@ -4,7 +4,7 @@
   "status": "published",
   "layout": "default",
   "metadata": {
-    "title": "Meridian — Global Satellite Internet",
+    "title": "Meridian \u2014 Global Satellite Internet",
     "description": "Connect from anywhere on Earth. Low-latency satellite internet for homes, businesses, and beyond.",
     "canonical": "https://www.meridian.local/"
   },
@@ -24,8 +24,7 @@
             "assetId": "ast_site_home_hero",
             "alt": "Light abstract hero background with satellite constellation"
           }
-        },
-        "$type": "component"
+        }
       },
       {
         "id": "why-meridian",
@@ -41,8 +40,7 @@
                 "icon": "globe",
                 "title": "Global coverage",
                 "description": "A constellation of low-orbit satellites keeps you connected across continents, oceans, and remote terrain."
-              },
-              "$type": "component"
+              }
             },
             {
               "id": "low-latency",
@@ -51,8 +49,7 @@
                 "icon": "speed",
                 "title": "Low latency",
                 "description": "Sub-50ms latency means video calls, gaming, and real-time control feel local, even in the middle of nowhere."
-              },
-              "$type": "component"
+              }
             },
             {
               "id": "easy-setup",
@@ -61,12 +58,10 @@
                 "icon": "setup",
                 "title": "Easy setup",
                 "description": "A compact terminal and a phone app. Point at the sky, power on, and get online in minutes."
-              },
-              "$type": "component"
+              }
             }
           ]
-        },
-        "$type": "component"
+        }
       },
       {
         "id": "stats",
@@ -94,8 +89,7 @@
               "suffix": ""
             }
           ]
-        },
-        "$type": "component"
+        }
       },
       {
         "id": "cta",
@@ -113,8 +107,7 @@
                 "variant": "primary",
                 "icon": "arrow_forward",
                 "iconPosition": "after"
-              },
-              "$type": "component"
+              }
             },
             {
               "id": "cta-secondary",
@@ -125,12 +118,10 @@
                 "variant": "outline",
                 "icon": "arrow_forward",
                 "iconPosition": "after"
-              },
-              "$type": "component"
+              }
             }
           ]
-        },
-        "$type": "component"
+        }
       }
     ]
   }

package/templates/common/starter-content/.content/schemas/site.schema.json

@@ -7,6 +7,15 @@
   "additionalProperties": true,
   "properties": {
     "$type": { "const": "site" },
+    "errorPages": {
+      "type": "object",
+      "required": ["notFound", "catchAll"],
+      "additionalProperties": false,
+      "properties": {
+        "notFound": { "type": "string", "pattern": "^/(?:[A-Za-z0-9._~-]+/)+$" },
+        "catchAll": { "type": "string", "pattern": "^/(?:[A-Za-z0-9._~-]+/)+$" }
+      }
+    },
     "id": { "type": "string", "minLength": 1 },
     "status": { "type": "string", "minLength": 1 },
     "title": { "type": "string", "minLength": 1 },

package/templates/nextjs/template/package.json.tmpl

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "ACI_CONTENT_PROVIDER=file next dev -H 0.0.0.0",
-    "build": "next build",
+    "build": "node ./node_modules/@gradial/aci/src/cli/emit-error-pages.mjs prepare && next build && node ./node_modules/@gradial/aci/src/cli/emit-error-pages.mjs emit",
     "preview": "next start -H 0.0.0.0",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx --test tests/**/*.test.ts",

package/templates/nextjs/template/src/aci/error-page-instrumentation.d.mts

@@ -0,0 +1,4 @@
+// Type surface for the customer-owned policy module beside this file
+// (authorable-error-pages D-15). Edit the .mjs; this declaration only needs
+// touching if you change the function's signature.
+export declare function pushErrorPageView(pageType: 'not_found' | 'error'): void;

package/templates/nextjs/template/src/aci/error-page-instrumentation.mjs

@@ -0,0 +1,38 @@
+// Error-page analytics policy — THIS FILE IS YOURS (customer-owned;
+// code-organization R-14 / authorable-error-pages D-15). The ACI SDK owns
+// the delivery mechanism (when this runs, serialization, the
+// data-aci-error-page marker); this file owns WHAT is pushed.
+//
+// Contract:
+// - pushErrorPageView MUST stay self-contained: browser globals only — no
+//   imports, no closed-over identifiers. The Astro seats and the 500.html
+//   emitter execute it STRINGIFIED via toString(), so anything outside the
+//   function body is lost.
+// - Emptying the body to a no-op disables error-page analytics on every
+//   surface (Next seats, Astro seats, 500.html) — the sanctioned
+//   alternative to GTM-container-side suppression.
+// - Plain .mjs on purpose: it is consumed verbatim, never transpiled.
+//
+// 'use client' (Next only, inert elsewhere): the not-found seat is a server
+// component and can only hand a function to the client-side instrumentation
+// component as a client reference.
+'use client';
+
+/**
+ * Pushes one `page_view` event per error-surface view (D-14 default
+ * payload). `page_path` is the visitor's requested path, so 404 reports
+ * double as a broken-link inventory.
+ *
+ * @param {'not_found' | 'error'} pageType
+ */
+export function pushErrorPageView(pageType) {
+  window.dataLayer = window.dataLayer || [];
+  window.dataLayer.push({
+    event: 'page_view',
+    page_type: pageType,
+    page_path: window.location.pathname,
+    page_location: window.location.href,
+    page_referrer: document.referrer || '(direct)',
+    page_title: document.title,
+  });
+}

package/templates/nextjs/template/src/app/error.tsx

@@ -0,0 +1,18 @@
+'use client';
+
+import { ErrorSeat } from '@gradial/aci/next/error-seat';
+import { registry } from '@/cms/registry';
+import { pushErrorPageView } from '../aci/error-page-instrumentation.mjs';
+
+// Next's app-error seat (client-only by contract). ErrorSeat renders the
+// page bound by site.json#errorPages.catchAll from content serialized into
+// the bundle at build time — nothing is fetched while the app is failing.
+// The analytics push comes from the site-owned policy module (D-15):
+// edit src/aci/error-page-instrumentation.mjs to customize or disable it.
+//
+// Coverage: render errors below the root layout. NOT covered here: root
+// layout errors (global-error), middleware failures, and platform 5xx —
+// those are served the static public/500.html emitted by the build.
+export default function AppError({ error }: { error: Error & { digest?: string } }) {
+  return <ErrorSeat registry={registry} error={error} pushErrorPageView={pushErrorPageView} />;
+}

package/templates/nextjs/template/src/app/not-found.tsx

@@ -0,0 +1,13 @@
+import { createNotFound } from '@gradial/aci/next';
+import { registry } from '@/cms/registry';
+import { pushErrorPageView } from '../aci/error-page-instrumentation.mjs';
+
+// Next's native not-found seat: the SDK catch-all invokes notFound() on
+// missing content, and this renders the page bound by
+// site.json#errorPages.notFound with a real HTTP 404. If that page is itself
+// missing at request time, the SDK falls back to its shipped default inline —
+// this seat never recurses and never throws.
+//
+// The analytics push comes from the site-owned policy module (D-15):
+// edit src/aci/error-page-instrumentation.mjs to customize or disable it.
+export default createNotFound(registry, { pushErrorPageView });