@gradial/aci 0.1.52-rc.4 → 0.1.52-rc.5

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.52-rc.4` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.52-rc.5` is a pre-1.0 public-surface reset for the ACI
 client SDK. Breaking changes from the old `0.1.x` accidental surface are
 intentional: the root import is framework-neutral, framework runtime behavior is
 behind explicit subpaths, and the first required customer path is React/Next.
@@ -8,7 +8,7 @@ behind explicit subpaths, and the first required customer path is React/Next.
 ## Install
 
 ```bash
-npm install @gradial/aci@0.1.52-rc.4 zod@^4
+npm install @gradial/aci@0.1.52-rc.5 zod@^4
 ```
 
 ## Root Import
@@ -78,13 +78,13 @@ host bundles select and serve immutable release artifacts.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.52-rc.4 init my-site --template next-starter
+npx @gradial/aci@0.1.52-rc.5 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.52-rc.4 init --list
+npx @gradial/aci@0.1.52-rc.5 init --list
 ```
 
 ## Personalization: The One-Tag Install

package/dist/cli/compile-registry.d.mts

@@ -1,2 +1,6 @@
 #!/usr/bin/env node
-export {};
+export function compileRegistry(options: any): Promise<{
+    registry: string;
+    schemas: string[];
+}>;
+export function generatePageSchema(schemaDir: any, componentEntries: any, outDir: any): Promise<string>;

package/dist/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';
@@ -18,14 +19,16 @@ try {
         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) {
     const required = ['components', 'layouts', 'output'];
@@ -440,9 +443,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' },
@@ -757,3 +761,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/dist/cli/validate-content.d.mts

@@ -1,2 +1,32 @@
 #!/usr/bin/env node
-export {};
+export function validateContent(options: any): Promise<{
+    warnings?: any[] | undefined;
+    success: boolean;
+    pagesValidated: number;
+    blocksValidated: number;
+    errors: ({
+        page: string;
+        message: string;
+        fragment?: undefined;
+        component?: undefined;
+        path?: undefined;
+    } | {
+        fragment: string;
+        message: string;
+        page?: undefined;
+        component?: undefined;
+        path?: undefined;
+    } | {
+        fragment: string;
+        component: any;
+        message: string;
+        page?: undefined;
+        path?: undefined;
+    } | {
+        fragment: string;
+        component: any;
+        path: any;
+        message: any;
+        page?: undefined;
+    })[];
+}>;

package/dist/cli/validate-content.mjs

@@ -19,21 +19,25 @@
  * 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)
+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;
-}
-catch (error) {
-    console.error(JSON.stringify({
-        success: false,
-        errors: [{ message: String(error?.message ?? error) }],
-    }, null, 2));
-    process.exitCode = 1;
+    }
 }
 // ---------------------------------------------------------------------------
 // Main
@@ -86,6 +90,22 @@ async function validateContent(options) {
         const blocks = collectBlocks(pageData);
         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,
@@ -348,6 +368,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}"` });
                 continue;
@@ -424,3 +451,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/dist/content/provider.d.ts

@@ -21,7 +21,6 @@ export interface FragmentEntry {
 }
 export interface LayoutEntry {
     name: string;
-    payloadRef: string;
     slots: LayoutSlot[];
     defaults?: Record<string, FragmentRef[]>;
 }

package/dist/content/resolve-slots.d.ts

@@ -1,9 +1,16 @@
 import type { LayoutEntry } from './provider.js';
 import type { KernelPageBlock } from './types.js';
-export interface FragmentData {
-    id: string;
+export interface FragmentBlock {
+    $type: 'component';
     component: string;
     props?: Record<string, unknown>;
 }
+export interface FragmentData {
+    fragmentId?: string;
+    id?: string;
+    block?: FragmentBlock;
+    component?: string;
+    props?: Record<string, unknown>;
+}
 export type FragmentLoader = (id: string) => Promise<FragmentData>;
 export declare function resolveSlots(layout: LayoutEntry, pageRegions: Record<string, KernelPageBlock[]>, getFragment: FragmentLoader): Promise<Record<string, KernelPageBlock[]>>;

package/dist/content/resolve-slots.js

@@ -11,10 +11,12 @@ export async function resolveSlots(layout, pageRegions, getFragment) {
             const blocks = [];
             for (const ref of defaults) {
                 const fragment = await getFragment(ref.fragmentId);
+                const block = fragment.block ?? { component: fragment.component ?? '', props: fragment.props };
                 blocks.push({
-                    id: fragment.id,
-                    component: fragment.component,
-                    props: fragment.props || {},
+                    $type: 'component',
+                    id: fragment.id ?? fragment.fragmentId ?? ref.fragmentId,
+                    component: block.component,
+                    props: block.props || {},
                 });
             }
             resolved[slot.name] = blocks;

package/dist/content/types.d.ts

@@ -42,11 +42,13 @@ export interface KernelPageSeo {
     canonical?: string;
 }
 export interface KernelPageBlock {
+    $type: 'component';
     id: string;
     component: string;
     props: Record<string, unknown>;
 }
 export interface KernelAtomicBlock {
+    $type: 'component';
     id: string;
     component: string;
     props: Record<string, unknown>;

package/dist/next/error-seat-payload.js

@@ -104,7 +104,7 @@ export function buildErrorSeatPayload(contentRoot, posture) {
                 if (!fragmentRef)
                     continue;
                 const fragment = readJSON(root, fragmentRef);
-                blocks.push({ id: fragment.id, component: fragment.component, props: fragment.props || {} });
+                blocks.push({ $type: 'component', id: fragment.id, component: fragment.component, props: fragment.props || {} });
             }
             if (blocks.length)
                 slots[slot.name] = blocks;

package/dist/providers/s3.js

@@ -78,13 +78,12 @@ export class S3ContentProvider {
     }
     async getLayout(name) {
         const manifest = await this.manifest();
-        const entry = manifest.layouts?.[name];
-        if (!entry) {
+        const layouts = manifest.layouts;
+        if (!layouts || !layouts[name]) {
             throw new LayoutNotFoundError(name);
         }
-        const ref = entry.payloadRef;
         try {
-            return await this.getJSON(ref);
+            return await this.getJSON(`layouts/${name}.json`);
         }
         catch (error) {
             throw new LayoutNotFoundError(name, error);
@@ -200,13 +199,7 @@ export class S3ContentProvider {
         }
         let page;
         try {
-            const parsed = JSON.parse(source);
-            if (parsed?.schemaVersion === 'gradial.ssr-page.v1' && parsed.page !== undefined) {
-                page = parsed.page;
-            }
-            else {
-                page = parsed;
-            }
+            page = JSON.parse(source);
         }
         catch (cause) {
             throw pageIntegrityError(`invalid JSON for ${tuple.contentRef}`, cause);

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.4",
+  "version": "0.1.52-rc.5",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -76,16 +76,6 @@
       "import": "./dist/next/error-seat.js",
       "default": "./dist/next/error-seat.js"
     },
-    "./next/middleware": {
-      "types": "./dist/next/middleware.d.ts",
-      "import": "./dist/next/middleware.js",
-      "default": "./dist/next/middleware.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",
@@ -156,11 +146,11 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.4",
-    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.4",
-    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.4",
-    "@gradial/aci-cli-linux-x64": "0.1.52-rc.4",
-    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.4",
-    "@gradial/aci-cli-win32-x64": "0.1.52-rc.4"
+    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.5",
+    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.5",
+    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.5",
+    "@gradial/aci-cli-linux-x64": "0.1.52-rc.5",
+    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.5",
+    "@gradial/aci-cli-win32-x64": "0.1.52-rc.5"
   }
 }

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/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,7 +23,7 @@ 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',
           versionId: 'v0001',

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

@@ -98,6 +98,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 +110,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 +143,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 +160,7 @@ export const containerContract = defineComponentContract({
         }
       },
       {
+        "$type": "component",
         "id": "secondary-cta",
         "component": "button",
         "props": {
@@ -182,6 +187,7 @@ The `button` component is a common atomic block:
 
 ```json
 {
+  "$type": "component",
   "id": "cta-button",
   "component": "button",
   "props": {
@@ -482,6 +488,7 @@ framework.
 ```json
 // .content/pages/home/_index.json (inside regions.main)
 {
+  "$type": "component",
   "id": "features",
   "component": "feature_showcase",
   "props": {
@@ -570,9 +577,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": {

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

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

package/templates/common/starter-content/.content/fragments/navbar/_index.json

@@ -1,25 +1,28 @@
 {
   "$type": "fragment",
   "fragmentId": "navbar",
-  "component": "site-navigation",
-  "props": {
-    "brandHref": "/",
-    "brandLabel": "Meridian",
-    "brandLogo": {
-      "src": "/assets/meridian-logo.svg",
-      "alt": "Meridian"
-    },
-    "navigation": [
-      { "id": "home", "label": "Home", "href": "/" },
-      { "id": "plans", "label": "Plans", "href": "/plans/" },
-      { "id": "devices", "label": "Devices", "href": "/devices/" },
-      { "id": "business", "label": "Business", "href": "/business/" },
-      { "id": "blog", "label": "Blog", "href": "/blog/" },
-      { "id": "about", "label": "About", "href": "/about/" }
-    ],
-    "utilities": [
-      { "id": "sign-in", "label": "Sign in", "href": "/sign-in/", "variant": "ghost" },
-      { "id": "contact-sales", "label": "Contact sales", "href": "/contact-sales/", "variant": "primary" }
-    ]
+  "block": {
+    "$type": "component",
+    "component": "site-navigation",
+    "props": {
+      "brandHref": "/",
+      "brandLabel": "Meridian",
+      "brandLogo": {
+        "src": "/assets/meridian-logo.svg",
+        "alt": "Meridian"
+      },
+      "navigation": [
+        { "id": "home", "label": "Home", "href": "/" },
+        { "id": "plans", "label": "Plans", "href": "/plans/" },
+        { "id": "devices", "label": "Devices", "href": "/devices/" },
+        { "id": "business", "label": "Business", "href": "/business/" },
+        { "id": "blog", "label": "Blog", "href": "/blog/" },
+        { "id": "about", "label": "About", "href": "/about/" }
+      ],
+      "utilities": [
+        { "id": "sign-in", "label": "Sign in", "href": "/sign-in/", "variant": "ghost" },
+        { "id": "contact-sales", "label": "Contact sales", "href": "/contact-sales/", "variant": "primary" }
+      ]
+    }
   }
 }

package/templates/common/starter-content/.content/fragments/site-footer/_index.json

@@ -1,62 +1,65 @@
 {
   "$type": "fragment",
   "fragmentId": "site-footer",
-  "component": "site-footer",
-  "props": {
-    "brandHref": "/",
-    "brandLabel": "Meridian",
-    "brandLogo": {
-      "src": "/assets/meridian-logo.svg",
-      "alt": "Meridian"
-    },
-    "columns": [
-      {
-        "id": "products",
-        "title": "Products",
-        "links": [
-          { "id": "plans", "label": "Plans", "href": "/plans/" },
-          { "id": "devices", "label": "Devices", "href": "/devices/" },
-          { "id": "coverage", "label": "Coverage", "href": "/coverage/" }
-        ]
+  "block": {
+    "$type": "component",
+    "component": "site-footer",
+    "props": {
+      "brandHref": "/",
+      "brandLabel": "Meridian",
+      "brandLogo": {
+        "src": "/assets/meridian-logo.svg",
+        "alt": "Meridian"
       },
-      {
-        "id": "solutions",
-        "title": "Solutions",
-        "links": [
-          { "id": "business", "label": "Business", "href": "/business/" },
-          { "id": "maritime", "label": "Maritime", "href": "/business/maritime/" },
-          { "id": "aerospace", "label": "Aerospace", "href": "/business/aerospace/" }
-        ]
-      },
-      {
-        "id": "resources",
-        "title": "Resources",
-        "links": [
-          { "id": "blog", "label": "Blog", "href": "/blog/" },
-          { "id": "documentation", "label": "Documentation", "href": "/docs/" },
-          { "id": "support", "label": "Support", "href": "/support/" }
-        ]
-      },
-      {
-        "id": "company",
-        "title": "Company",
-        "links": [
-          { "id": "about", "label": "About us", "href": "/about/" },
-          { "id": "careers", "label": "Careers", "href": "/careers/" },
-          { "id": "contact", "label": "Contact", "href": "/contact/" }
-        ]
-      }
-    ],
-    "social": [
-      { "id": "x", "label": "X", "href": "https://x.com/meridian", "icon": "X" },
-      { "id": "linkedin", "label": "LinkedIn", "href": "https://www.linkedin.com/company/meridian", "icon": "in" },
-      { "id": "youtube", "label": "YouTube", "href": "https://www.youtube.com/meridian", "icon": "YT" }
-    ],
-    "legalLinks": [
-      { "id": "terms", "label": "Terms of Service", "href": "/terms/" },
-      { "id": "privacy", "label": "Privacy Policy", "href": "/privacy/" },
-      { "id": "security", "label": "Security", "href": "/security/" }
-    ],
-    "copyright": "Copyright (c) 2026 Meridian Satellite Networks, Inc. All rights reserved."
+      "columns": [
+        {
+          "id": "products",
+          "title": "Products",
+          "links": [
+            { "id": "plans", "label": "Plans", "href": "/plans/" },
+            { "id": "devices", "label": "Devices", "href": "/devices/" },
+            { "id": "coverage", "label": "Coverage", "href": "/coverage/" }
+          ]
+        },
+        {
+          "id": "solutions",
+          "title": "Solutions",
+          "links": [
+            { "id": "business", "label": "Business", "href": "/business/" },
+            { "id": "maritime", "label": "Maritime", "href": "/business/maritime/" },
+            { "id": "aerospace", "label": "Aerospace", "href": "/business/aerospace/" }
+          ]
+        },
+        {
+          "id": "resources",
+          "title": "Resources",
+          "links": [
+            { "id": "blog", "label": "Blog", "href": "/blog/" },
+            { "id": "documentation", "label": "Documentation", "href": "/docs/" },
+            { "id": "support", "label": "Support", "href": "/support/" }
+          ]
+        },
+        {
+          "id": "company",
+          "title": "Company",
+          "links": [
+            { "id": "about", "label": "About us", "href": "/about/" },
+            { "id": "careers", "label": "Careers", "href": "/careers/" },
+            { "id": "contact", "label": "Contact", "href": "/contact/" }
+          ]
+        }
+      ],
+      "social": [
+        { "id": "x", "label": "X", "href": "https://x.com/meridian", "icon": "X" },
+        { "id": "linkedin", "label": "LinkedIn", "href": "https://www.linkedin.com/company/meridian", "icon": "in" },
+        { "id": "youtube", "label": "YouTube", "href": "https://www.youtube.com/meridian", "icon": "YT" }
+      ],
+      "legalLinks": [
+        { "id": "terms", "label": "Terms of Service", "href": "/terms/" },
+        { "id": "privacy", "label": "Privacy Policy", "href": "/privacy/" },
+        { "id": "security", "label": "Security", "href": "/security/" }
+      ],
+      "copyright": "Copyright (c) 2026 Meridian Satellite Networks, Inc. All rights reserved."
+    }
   }
 }

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

@@ -11,6 +11,7 @@
   "regions": {
     "main": [
       {
+        "$type": "component",
         "id": "about-hero",
         "component": "home_hero",
         "props": {
@@ -27,12 +28,14 @@
         }
       },
       {
+        "$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/home/_index.json

@@ -11,6 +11,7 @@
   "regions": {
     "main": [
       {
+        "$type": "component",
         "id": "hero",
         "component": "home_hero",
         "props": {
@@ -27,6 +28,7 @@
         }
       },
       {
+        "$type": "component",
         "id": "why-meridian",
         "component": "feature_grid",
         "props": {
@@ -34,6 +36,7 @@
           "subtitle": "Engineered for the edges of the world.",
           "features": [
             {
+              "$type": "component",
               "id": "global-coverage",
               "component": "feature_card",
               "props": {
@@ -43,6 +46,7 @@
               }
             },
             {
+              "$type": "component",
               "id": "low-latency",
               "component": "feature_card",
               "props": {
@@ -52,6 +56,7 @@
               }
             },
             {
+              "$type": "component",
               "id": "easy-setup",
               "component": "feature_card",
               "props": {
@@ -64,6 +69,7 @@
         }
       },
       {
+        "$type": "component",
         "id": "stats",
         "component": "stats_bar",
         "props": {
@@ -92,6 +98,7 @@
         }
       },
       {
+        "$type": "component",
         "id": "cta",
         "component": "container",
         "props": {
@@ -99,6 +106,7 @@
           "className": "items-center justify-center text-center",
           "content": [
             {
+              "$type": "component",
               "id": "cta-primary",
               "component": "button",
               "props": {
@@ -110,6 +118,7 @@
               }
             },
             {
+              "$type": "component",
               "id": "cta-secondary",
               "component": "button",
               "props": {