@gradial/aci 0.1.45 → 0.1.47

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

@@ -98,7 +98,6 @@ The `home` slug is special-cased to route `/`. All other slugs map directly.
 
 ```json
 {
-  "$type": "component",
   "id": "hero-section",
   "component": "home_hero",
   "props": {
@@ -110,7 +109,6 @@ The `home` slug is special-cased to route `/`. All other slugs map directly.
 ```
 
 - `component` must match a contract `id` exactly.
-- Every embedded block must declare `"$type": "component"`.
 - `props` must validate against the contract's Zod schema.
 - `id` is unique within the page.
 
@@ -143,14 +141,12 @@ export const containerContract = defineComponentContract({
 **Content JSON:**
 ```json
 {
-  "$type": "component",
   "id": "cta-section",
   "component": "container",
   "props": {
     "className": "space-y-4",
     "content": [
       {
-        "$type": "component",
         "id": "primary-cta",
         "component": "button",
         "props": {
@@ -160,7 +156,6 @@ export const containerContract = defineComponentContract({
         }
       },
       {
-        "$type": "component",
         "id": "secondary-cta",
         "component": "button",
         "props": {
@@ -187,7 +182,6 @@ The `button` component is a common atomic block:
 
 ```json
 {
-  "$type": "component",
   "id": "cta-button",
   "component": "button",
   "props": {
@@ -244,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.
@@ -417,7 +482,6 @@ framework.
 ```json
 // .content/pages/home/_index.json (inside regions.main)
 {
-  "$type": "component",
   "id": "features",
   "component": "feature_showcase",
   "props": {
@@ -506,10 +570,9 @@ export default [
 ];
 ```
 
-Fragment content lives in `.content/fragments/{id}/_index.json` and retains
-the resource envelope `"$type": "fragment"` while declaring `component` +
-`props`. Chrome components (Header, Footer) are registered in the registry
-alongside page components.
+Fragment content lives in `.content/fragments/{id}/_index.json` and has
+a `component` + `props` just like page blocks. Chrome components (Header,
+Footer) are registered in the registry alongside page components.
 
 The `layout` field in page JSON is **required** — there is no implicit
 default. Every page must declare which layout it uses.

package/templates/common/.agents/skills/authoring/references/block-slots.md

@@ -113,14 +113,12 @@ type RenderChildren<T extends readonly BlockRef[]> = (blocks: T) => Promise<Reac
 
 ```json
 {
-  "$type": "component",
   "id": "cta-section",
   "component": "container",
   "props": {
     "theme": "dark",
     "blocks": [
       {
-        "$type": "component",
         "id": "primary-cta",
         "component": "callout",
         "props": {
@@ -129,7 +127,6 @@ type RenderChildren<T extends readonly BlockRef[]> = (blocks: T) => Promise<Reac
         }
       },
       {
-        "$type": "component",
         "id": "heading",
         "component": "heading",
         "props": {

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/pages/home/_index.json

@@ -11,7 +11,6 @@
   "regions": {
     "main": [
       {
-        "$type": "component",
         "id": "hero",
         "component": "home_hero",
         "props": {
@@ -28,7 +27,6 @@
         }
       },
       {
-        "$type": "component",
         "id": "why-meridian",
         "component": "feature_grid",
         "props": {
@@ -36,7 +34,6 @@
           "subtitle": "Engineered for the edges of the world.",
           "features": [
             {
-              "$type": "component",
               "id": "global-coverage",
               "component": "feature_card",
               "props": {
@@ -46,7 +43,6 @@
               }
             },
             {
-              "$type": "component",
               "id": "low-latency",
               "component": "feature_card",
               "props": {
@@ -56,7 +52,6 @@
               }
             },
             {
-              "$type": "component",
               "id": "easy-setup",
               "component": "feature_card",
               "props": {
@@ -69,7 +64,6 @@
         }
       },
       {
-        "$type": "component",
         "id": "personalization-choice",
         "component": "personalization_choice",
         "props": {
@@ -81,7 +75,6 @@
         }
       },
       {
-        "$type": "component",
         "id": "stats",
         "component": "stats_bar",
         "props": {
@@ -94,7 +87,6 @@
         }
       },
       {
-        "$type": "component",
         "id": "cta",
         "component": "container",
         "props": {
@@ -102,7 +94,6 @@
           "className": "items-center justify-center text-center",
           "content": [
             {
-              "$type": "component",
               "id": "cta-primary",
               "component": "button",
               "props": {
@@ -114,7 +105,6 @@
               }
             },
             {
-              "$type": "component",
               "id": "cta-secondary",
               "component": "button",
               "props": {

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

@@ -11,7 +11,6 @@
   "regions": {
     "main": [
       {
-        "$type": "component",
         "id": "about-hero",
         "component": "home_hero",
         "props": {
@@ -28,14 +27,12 @@
         }
       },
       {
-        "$type": "component",
         "id": "about-actions",
         "component": "container",
         "props": {
           "className": "items-center justify-center text-center",
           "content": [
             {
-              "$type": "component",
               "id": "home-link",
               "component": "button",
               "props": {

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"
+          }
+        }
+      }
+    ]
+  }
+}