@gradial/aci 0.1.52-rc.2 → 0.1.52-rc.22

package/dist/react/index.d.ts

@@ -29,12 +29,11 @@ export declare function Image({ image, value, ...attrs }: ImageProps): import("r
     style?: import("react").CSSProperties | undefined;
     dir?: string | undefined | undefined;
     hidden?: boolean | undefined | undefined;
+    children?: ReactNode;
     dangerouslySetInnerHTML?: {
         __html: string | TrustedHTML;
     } | undefined | undefined;
-    children?: ReactNode;
     className?: string | undefined | undefined;
-    lang?: string | undefined | undefined;
     crossOrigin?: "" | "anonymous" | "use-credentials" | undefined;
     fetchPriority?: "high" | "low" | "auto" | undefined | undefined;
     useMap?: string | undefined | undefined;
@@ -49,6 +48,7 @@ export declare function Image({ image, value, ...attrs }: ImageProps): import("r
     contextMenu?: string | undefined | undefined;
     draggable?: (boolean | "true" | "false") | undefined;
     enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined | undefined;
+    lang?: string | undefined | undefined;
     nonce?: string | undefined | undefined;
     spellCheck?: (boolean | "true" | "false") | undefined;
     tabIndex?: number | undefined | undefined;

package/dist/testing/index.js

@@ -53,9 +53,9 @@ export class FixtureContentProvider {
         return [...this.pages.entries()]
             .sort(([a], [b]) => a.localeCompare(b))
             .map(([routePath, page]) => ({
-            slug: routePath === '/' ? 'home' : routePath.replace(/^\//, ''),
+            slug: routePath === '/' ? '' : routePath.replace(/^\//, ''),
             path: routePath,
-            payloadRef: `routes/${routePath === '/' ? 'home' : routePath.replace(/^\//, '')}.json`,
+            payloadRef: routePath === '/' ? 'routes/index.json' : `routes/${routePath.replace(/^\//, '')}.json`,
             digest: '',
         }));
     }

package/dist/types/block-ref.d.ts

@@ -5,6 +5,7 @@ export interface BlockRefMeta {
     multiple: boolean;
 }
 declare const blockRefBase: z.ZodObject<{
+    $type: z.ZodLiteral<"component">;
     id: z.ZodString;
     component: z.ZodString;
     props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -12,6 +13,7 @@ declare const blockRefBase: z.ZodObject<{
 type InferContractProps<T> = T extends ComponentContract<string, infer Schema> ? Schema extends z.ZodType<infer P> ? P : Record<string, unknown> : Record<string, unknown>;
 type InferContractId<T> = T extends ComponentContract<infer Id, unknown> ? Id : never;
 export type BlockRefEntry<T extends ComponentContract> = {
+    $type: 'component';
     id: string;
     component: InferContractId<T>;
     props: InferContractProps<T>;

package/dist/types/block-ref.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 const BLOCK_REF_KEY = '_gradialBlockRef';
 const blockRefBase = z.object({
+    $type: z.literal('component'),
     id: z.string().min(1),
     component: z.string().min(1),
     props: z.record(z.string(), z.unknown()),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.52-rc.2",
+  "version": "0.1.52-rc.22",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -41,6 +41,14 @@
       "types": "./dist/compiler/index.d.ts",
       "import": "./dist/compiler/index.js"
     },
+    "./expression-capabilities": {
+      "types": "./dist/edge/expression-capabilities.v1.d.ts",
+      "import": "./dist/edge/expression-capabilities.v1.js"
+    },
+    "./mintlify": {
+      "types": "./dist/mintlify/index.d.ts",
+      "import": "./dist/mintlify/index.js"
+    },
     "./providers/file": {
       "types": "./dist/providers/file.d.ts",
       "import": "./dist/providers/file.js"
@@ -76,6 +84,11 @@
       "import": "./dist/next/error-seat.js",
       "default": "./dist/next/error-seat.js"
     },
+    "./next/asset-route": {
+      "types": "./dist/next/asset-route.d.ts",
+      "import": "./dist/next/asset-route.js",
+      "default": "./dist/next/asset-route.js"
+    },
     "./next/server": {
       "types": "./dist/next/server.d.ts",
       "import": "./dist/next/server.js",
@@ -146,11 +159,11 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.2",
-    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.2",
-    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.2",
-    "@gradial/aci-cli-linux-x64": "0.1.52-rc.2",
-    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.2",
-    "@gradial/aci-cli-win32-x64": "0.1.52-rc.2"
+    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.22",
+    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.22",
+    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.22",
+    "@gradial/aci-cli-linux-x64": "0.1.52-rc.22",
+    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.22",
+    "@gradial/aci-cli-win32-x64": "0.1.52-rc.22"
   }
 }

package/src/cli/compile-registry.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import { ImageSchema } from '../types/image.ts';
 import { VideoSchema } from '../types/video.ts';
@@ -19,14 +20,15 @@ try {
   if (!globalThis.React) globalThis.React = React;
 } catch { /* react not available — component files without JSX will still work */ }
 
-const args = parseArgs(process.argv.slice(2));
-
-try {
-  const result = await compileRegistry(args);
-  console.log(JSON.stringify({ success: true, ...result, errors: [] }, null, 2));
-} catch (error) {
-  console.error(JSON.stringify({ success: false, errors: [String(error?.message ?? error)] }, null, 2));
-  process.exitCode = 1;
+if (isMainModule()) {
+  const args = parseArgs(process.argv.slice(2));
+  try {
+    const result = await compileRegistry(args);
+    console.log(JSON.stringify({ success: true, ...result, errors: [] }, null, 2));
+  } catch (error) {
+    console.error(JSON.stringify({ success: false, errors: [String(error?.message ?? error)] }, null, 2));
+    process.exitCode = 1;
+  }
 }
 
 async function compileRegistry(options) {
@@ -430,9 +432,10 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
   const defs = {
     baseBlock: {
       type: 'object',
-      required: ['id', 'component', 'props'],
+      required: ['$type', 'id', 'component', 'props'],
       additionalProperties: true,
       properties: {
+        $type: { const: 'component' },
         id: { type: 'string', minLength: 1 },
         component: { type: 'string' },
         props: { type: 'object' },
@@ -741,3 +744,14 @@ function parseArgs(argv) {
   }
   return out;
 }
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(path.resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+export { compileRegistry, generatePageSchema };

package/src/cli/mintlify-render.mjs

@@ -0,0 +1,9 @@
+import path from 'node:path';
+import { loadCompiledMintlifySource, materializeMintlifySite } from '../../dist/mintlify/index.js';
+
+const [sourceArg, compiledArg, outputArg] = process.argv.slice(2);
+if (!sourceArg || !compiledArg || !outputArg) {
+  throw new Error('Mintlify renderer requires content, compiled, and output directories');
+}
+const source = await loadCompiledMintlifySource(path.resolve(sourceArg), path.resolve(compiledArg));
+await materializeMintlifySite({ ...source, outputDir: path.resolve(outputArg) });

package/src/cli/validate-content.mjs

@@ -19,21 +19,24 @@
  * Uses the JSON schemas generated by compile-registry — portable, no React/CSS
  * imports needed, same schemas usable by Go backend or other tools.
  */
+import { realpathSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
-
-const args = parseArgs(process.argv.slice(2));
-
-try {
-  const result = await validateContent(args);
-  console.log(JSON.stringify(result, null, 2));
-  if (!result.success) process.exitCode = 1;
-} catch (error) {
-  console.error(JSON.stringify({
-    success: false,
-    errors: [{ message: String(error?.message ?? error) }],
-  }, null, 2));
-  process.exitCode = 1;
+import { fileURLToPath } from 'node:url';
+
+if (isMainModule()) {
+  const args = parseArgs(process.argv.slice(2));
+  try {
+    const result = await validateContent(args);
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.success) process.exitCode = 1;
+  } catch (error) {
+    console.error(JSON.stringify({
+      success: false,
+      errors: [{ message: String(error?.message ?? error) }],
+    }, null, 2));
+    process.exitCode = 1;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -95,6 +98,24 @@ async function validateContent(options) {
     for (const block of blocks) {
       blocksValidated++;
 
+      if (!block || typeof block !== 'object') {
+        collector.push({
+          page: relativePath,
+          blockId: '<unknown>',
+          message: 'page region entry must be a component block',
+        });
+        continue;
+      }
+
+      if (block.$type !== 'component') {
+        collector.push({
+          page: relativePath,
+          blockId: block.id ?? '<unknown>',
+          path: '$type',
+          message: 'block "$type" must be "component"',
+        });
+      }
+
       if (!block.component) {
         collector.push({
           page: relativePath,
@@ -380,6 +401,13 @@ function validateNestedSlots(parentBlock, componentMap, schemaMap, path = 'props
         issues.push({ path: nestedPath, message: `${parentBlock.component}: block ref child must be a block` });
         continue;
       }
+      if (nestedBlock.$type !== 'component') {
+        issues.push({
+          path: `${nestedPath}.$type`,
+          message: `${parentBlock.component}: block ref child "$type" must be "component"`,
+        });
+        continue;
+      }
 
       if (!componentMap.has(nestedBlock.component)) {
         issues.push({ path: `${nestedPath}.component`, message: `${parentBlock.component}: unknown nested component "${nestedBlock.component}"` });
@@ -450,3 +478,14 @@ function parseArgs(argv) {
   }
   return out;
 }
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(path.resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+export { validateContent };

package/src/types/block-ref.test.ts

@@ -0,0 +1,45 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { z } from 'zod';
+
+import { compileSchema } from '../compiler/zod-to-jsonschema.js';
+import { defineComponentContract } from '../define-component.js';
+import { blockRefArray } from './block-ref.js';
+
+const childContract = defineComponentContract({
+  id: 'child',
+  props: z.object({
+    label: z.string(),
+  }),
+});
+
+test('block references require and accept the component discriminator', () => {
+  const schema = blockRefArray([childContract]);
+  const typed = {
+    $type: 'component',
+    id: 'child-1',
+    component: 'child',
+    props: { label: 'Hello' },
+  };
+
+  assert.equal(schema.safeParse([typed]).success, true);
+  assert.equal(schema.safeParse([{
+    id: typed.id,
+    component: typed.component,
+    props: typed.props,
+  }]).success, false);
+});
+
+test('compiled block-reference schema exposes the component discriminator', () => {
+  const compiled = compileSchema(blockRefArray([childContract])) as {
+    items?: {
+      properties?: Record<string, { const?: string }>;
+      required?: string[];
+      additionalProperties?: boolean;
+    };
+  };
+
+  assert.equal(compiled.items?.properties?.$type?.const, 'component');
+  assert.equal(compiled.items?.required?.includes('$type'), true);
+  assert.equal(compiled.items?.additionalProperties, false);
+});

package/src/types/block-ref.ts

@@ -9,6 +9,7 @@ export interface BlockRefMeta {
 }
 
 const blockRefBase = z.object({
+  $type: z.literal('component'),
   id: z.string().min(1),
   component: z.string().min(1),
   props: z.record(z.string(), z.unknown()),
@@ -21,6 +22,7 @@ type InferContractProps<T> = T extends ComponentContract<string, infer Schema>
 type InferContractId<T> = T extends ComponentContract<infer Id, unknown> ? Id : never;
 
 export type BlockRefEntry<T extends ComponentContract> = {
+  $type: 'component';
   id: string;
   component: InferContractId<T>;
   props: InferContractProps<T>;

package/templates/astro/starter-content/src/fixtures/atomicBlocks.ts

@@ -13,17 +13,18 @@ export const atomicBlockStoryFixtures: AtomicBlockStoryFixture[] = [
     storybookId: 'core-atomic-blocks-button--variants',
     title: 'Button / All Variants',
     block: {
+      $type: 'component',
       id: 'fixture-button-variants',
       component: 'container',
       props: {
         theme: 'auto',
         blocks: [
-          { id: 'btn-primary', component: 'button', props: { label: 'Primary button', href: '#', variant: 'primary' } },
-          { id: 'btn-secondary', component: 'button', props: { label: 'Secondary button', href: '#', variant: 'secondary' } },
-          { id: 'btn-tertiary', component: 'button', props: { label: 'Tertiary button', href: '#', variant: 'tertiary' } },
-          { id: 'btn-icon-before', component: 'button', props: { label: 'Icon before', href: '#', variant: 'primary', icon: 'arrow-right', iconPosition: 'before' } },
-          { id: 'btn-icon-after', component: 'button', props: { label: 'Icon after', href: '#', variant: 'secondary', icon: 'arrow-right', iconPosition: 'after' } },
-          { id: 'btn-new-window', component: 'button', props: { label: 'Opens in new tab', href: 'https://example.com', variant: 'primary', newWindow: true, icon: 'arrow-right', iconPosition: 'after' } }
+          { $type: 'component', id: 'btn-primary', component: 'button', props: { label: 'Primary button', href: '#', variant: 'primary' } },
+          { $type: 'component', id: 'btn-secondary', component: 'button', props: { label: 'Secondary button', href: '#', variant: 'secondary' } },
+          { $type: 'component', id: 'btn-tertiary', component: 'button', props: { label: 'Tertiary button', href: '#', variant: 'tertiary' } },
+          { $type: 'component', id: 'btn-icon-before', component: 'button', props: { label: 'Icon before', href: '#', variant: 'primary', icon: 'arrow-right', iconPosition: 'before' } },
+          { $type: 'component', id: 'btn-icon-after', component: 'button', props: { label: 'Icon after', href: '#', variant: 'secondary', icon: 'arrow-right', iconPosition: 'after' } },
+          { $type: 'component', id: 'btn-new-window', component: 'button', props: { label: 'Opens in new tab', href: 'https://example.com', variant: 'primary', newWindow: true, icon: 'arrow-right', iconPosition: 'after' } }
         ]
       }
     }

package/templates/astro/starter-content/src/fixtures/composition.ts

@@ -14,14 +14,15 @@ export const compositionStoryFixtures: CompositionStoryFixture[] = [
     storybookId: 'composition-container--buttons',
     title: 'Container / Buttons',
     block: {
+      $type: 'component',
       id: 'fixture-container-buttons',
       component: 'container',
       props: {
         theme: 'auto',
         className: 'space-y-4',
         blocks: [
-          { id: 'btn-1', component: 'button', props: { label: 'Primary action', href: '#', variant: 'primary', icon: 'arrow_forward', iconPosition: 'after' } },
-          { id: 'btn-2', component: 'button', props: { label: 'Secondary action', href: '#', variant: 'secondary' } }
+          { $type: 'component', id: 'btn-1', component: 'button', props: { label: 'Primary action', href: '#', variant: 'primary', icon: 'arrow_forward', iconPosition: 'after' } },
+          { $type: 'component', id: 'btn-2', component: 'button', props: { label: 'Secondary action', href: '#', variant: 'secondary' } }
         ]
       }
     }

package/templates/astro/starter-content/src/fixtures/sections.ts

@@ -14,6 +14,7 @@ export const sectionStoryFixtures: SectionStoryFixture[] = [
     storybookId: 'sections-home-hero--default',
     title: 'Home Hero',
     block: {
+      $type: 'component',
       id: 'fixture-home-hero',
       component: 'home_hero',
       props: {
@@ -22,9 +23,9 @@ export const sectionStoryFixtures: SectionStoryFixture[] = [
         description: 'One content model, three renderers. Build once in Next.js, Astro, and SvelteKit—then prove parity with shared fixtures.',
         ctaLabel: 'Get started',
         ctaHref: '/docs',
-          image: {
+        image: {
           $type: 'gradial.image',
-          assetId: 'fixture_seattle',
+          assetId: '3Ih26etWBTYfnAd0EjD0pP2h902',
           versionId: 'v0001',
           alt: 'Seattle skyline at dusk',
           sources: [

package/templates/astro/template/package.json.tmpl

@@ -14,7 +14,7 @@
     "build:storybook": "storybook build"
   },
   "engines": {
-    "node": ">=22",
+    "node": ">=24",
     "npm": ">=10"
   },
   "dependencies": {

package/templates/astro/template/src/layouts/SiteLayout.astro

@@ -48,8 +48,8 @@ const { title, description, canonical, siteName = 'Gradial', collectTag, assignm
       // island (@astrojs/react + @c15t/react) or any setup built on
       // c15t's createConsentManagerStore; this bridge picks it up either
       // way. Without a c15t setup the poll gives up silently and only the
-      // JS consent API (aci('consent', …) under the manual preset) writes
-      // envelopes.
+      // JS consent API (aci('consent', …)) writes envelopes — it is live
+      // under every preset, including c15t.
       //
       // Consents are mirrored only after a real visitor decision
       // (consentInfo set), never for pre-decision defaults, so the SDK

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

@@ -152,6 +152,56 @@ Optional (disabled by default):
 
 ## Troubleshooting
 
+### Deploying a starter to a hosted Vercel tenant
+
+Run the CLI from the starter repository root (where `.aci.yaml` lives), or
+pass `--site-dir .` from that directory. Do not pass an absolute site path
+from another working directory: older CLI versions can serialize it as a
+`../../../tmp/...` source folder, which makes the server-side build fail with
+a generic HTTP 500. The source ref must also be a pushed, cloneable branch;
+`ref: HEAD` from a detached worktree is not cloneable by the build service.
+
+The hosted publish sequence is:
+
+1. `GRADIAL_CODE_SOURCE_TOKEN="$(gh auth token)" aci code-build --site-dir . --branch <test-branch> ...`
+2. `aci branch land <test-branch>` to move the artifact link to `main`.
+3. Promote `/config/site.json` and the content paths needed by the release.
+4. Run `aci release publish --activate ...`.
+
+Match the tenant rendering mode to the starter's actual route capability. A
+Next starter with `dynamicParams = false` and no release-scoped runtime route
+is an SSG starter and must use `rendering.mode = "ssg"`; `ssr` is only valid
+when the frontend can resolve arbitrary host release routes at request time.
+A mismatch can build successfully but then fail SSG rendering or return a
+live Next 404 after the host rewrites a CMS page.
+
+Injected platform functions must be dependency-closed inside their own
+`.vercel/output/functions/<name>.func` mount. A prebuilt Vercel deploy does not
+install a function-local `package.json` after upload. Native dependencies such
+as `sharp` therefore belong to the host-function artifact, built for Vercel's
+Linux/x64 runtime and injected beside the handler; never add them to the
+starter's `package.json` merely to make a platform function resolve.
+
+Publish validates `refs/heads/live`, not only `main`. If `main` deletes a
+stale incompatible page or fragment that was previously promoted, promote
+that same path from `main` with `aci promote --path ... --yes`; because the
+source path is absent, the promote records a delete on `live`. This is the
+API-safe way to remove old live content—direct writes to `live` are forbidden.
+
+The same rule applies to breaking DAM identifier changes: every
+`dam.assetRef` in `live` is resolved during publish, so one legacy identifier
+blocks the release. Update the reference on a candidate branch through
+`aci content push`, land it, and promote that exact content path before
+publishing again. Do not weaken identifier validation or reactivate an old
+release to bypass the content migration.
+
+Legacy assets themselves are replaced through the product API, not rewritten
+in storage: download or retain the needed source bytes, upload them again so
+DAM creates fresh canonical IDs, approve them, replace every content reference,
+then land, promote, and publish the affected paths. This is the supported
+breaking cutover for pre-public tenants; there is no `ast_` alias or bulk
+object-store migration path.
+
 ### "Unknown component" error during content compile
 
 The content JSON references a `component` name that is not in the contract
@@ -209,3 +259,9 @@ development, design tokens, and the full contract/runtime split.
 
 Read `.agents/skills/migration/SKILL.md` for reverse-engineering a live
 site or design into ACI.
+
+## Deep Dive: DAM Delivery
+
+Read `.agents/skills/dam-delivery/SKILL.md` for signed on-demand image
+transform URLs: when to mint them, the closed parameter contract, expiry
+semantics, and why they must never be baked into published payloads.

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

@@ -78,12 +78,13 @@ Pages map to URL routes by their folder path under `/pages/`:
 
 | Page Path | Route |
 |-----------|-------|
-| `/pages/home/_index.json` | `/` |
+| `/pages/_index.json` | `/` |
 | `/pages/about/_index.json` | `/about` |
 | `/pages/products/_index.json` | `/products` |
 | `/pages/products/shoes/_index.json` | `/products/shoes` |
 
-The `home` slug is special-cased to route `/`. All other slugs map directly.
+The empty slug is the site root. Every named folder maps directly, including
+`/pages/home/_index.json` at `/home`.
 
 ### Content Rules
 
@@ -98,6 +99,7 @@ The `home` slug is special-cased to route `/`. All other slugs map directly.
 
 ```json
 {
+  "$type": "component",
   "id": "hero-section",
   "component": "home_hero",
   "props": {
@@ -109,6 +111,7 @@ 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.
 
@@ -141,12 +144,14 @@ 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": {
@@ -156,6 +161,7 @@ export const containerContract = defineComponentContract({
         }
       },
       {
+        "$type": "component",
         "id": "secondary-cta",
         "component": "button",
         "props": {
@@ -182,6 +188,7 @@ The `button` component is a common atomic block:
 
 ```json
 {
+  "$type": "component",
   "id": "cta-button",
   "component": "button",
   "props": {
@@ -480,8 +487,9 @@ framework.
 #### 5. Add content
 
 ```json
-// .content/pages/home/_index.json (inside regions.main)
+// .content/pages/_index.json (inside regions.main)
 {
+  "$type": "component",
   "id": "features",
   "component": "feature_showcase",
   "props": {
@@ -570,9 +578,10 @@ export default [
 ];
 ```
 
-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.
+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.
 
 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,12 +113,14 @@ 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": {
@@ -127,6 +129,7 @@ type RenderChildren<T extends readonly BlockRef[]> = (blocks: T) => Promise<Reac
         }
       },
       {
+        "$type": "component",
         "id": "heading",
         "component": "heading",
         "props": {