@gradial/aci 0.1.45 → 0.1.46

package/dist/next/vercel-s3-personalization.js

@@ -2,6 +2,7 @@ import { GetObjectCommand, HeadObjectCommand, PutObjectCommand, S3Client, } from
 import { awsCredentialsProvider } from '@vercel/oidc-aws-credentials-provider';
 import { getUncachedEdgeConfigValue } from './edge-config.js';
 import { IdentityErasureFencedError } from './personalization-host.js';
+import { decodeEdgeRouteProjectionV1, edgeRoutesV1Key, } from './vercel-edge-projection-v1.js';
 const ENVELOPE_DIGEST_METADATA_KEY = 'aci-envelope-sha256';
 const COLLECTION_GATE_ETAG_METADATA_KEY = 'aci-collection-gate-etag';
 const COLLECTION_GATE_STATE_METADATA_KEY = 'aci-collection-gate-state';
@@ -406,12 +407,13 @@ export class VercelEdgeConfigRouteStore {
         this.siteId = siteId;
     }
     async readEdgeManifest(releaseId) {
-        const value = await getUncachedEdgeConfigValue(this.edgeConfig, edgeRoutesKey(this.siteId, releaseId));
-        if (!value)
+        const value = await getUncachedEdgeConfigValue(this.edgeConfig, edgeRoutesV1Key(this.siteId, releaseId));
+        if (value == null)
             return null;
-        if (typeof value === 'string')
-            return JSON.parse(value);
-        return value;
+        return decodeEdgeRouteProjectionV1(value, {
+            siteId: this.siteId,
+            releaseId,
+        });
     }
 }
 export function createVercelS3PersonalizationStore(config) {
@@ -531,12 +533,6 @@ function cleanKey(value) {
 function joinKey(...parts) {
     return parts.map(cleanKey).filter(Boolean).join('/');
 }
-function edgeRoutesKey(siteId, releaseId) {
-    return `edgeRoutes_${edgeKeySegment(siteId)}_${edgeKeySegment(releaseId)}`;
-}
-function edgeKeySegment(value) {
-    return value.replace(/[^A-Za-z0-9_-]/g, '_');
-}
 function isNotFound(error) {
     const value = error;
     return value?.$metadata?.httpStatusCode === 404 || value?.name === 'NoSuchKey' || value?.name === 'NotFound';

package/dist/providers/s3.d.ts

@@ -32,10 +32,8 @@ export declare class S3ContentProvider implements ContentProvider {
     getSiteConfig<T = unknown>(): Promise<T>;
     getPage<T = unknown>(route: string): Promise<T>;
     /**
-     * getPageByRef serves the exact payload the edge selected (the
-     * X-Aci-Content-Ref contract): base page or variant. Only refs the
-     * release manifest declares are served — the header names published
-     * content, it cannot address arbitrary keys.
+     * getPageByRef serves an exact payload the manifest declares. The stricter
+     * route-bound selection used by server rendering stays package-internal.
      */
     getPageByRef<T = unknown>(payloadRef: string): Promise<T>;
     getFragment<T = unknown>(id: string): Promise<T>;

package/dist/providers/s3.js

@@ -1,8 +1,9 @@
 import crypto from 'node:crypto';
 import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3';
 import { awsCredentialsProvider } from '@vercel/oidc-aws-credentials-provider';
-import { FragmentNotFoundError, LayoutNotFoundError, PageNotFoundError } from '../content/provider.js';
+import { FragmentNotFoundError, LayoutNotFoundError, PageNotFoundError, } from '../content/provider.js';
 import { normalizeRoute } from '../content/routes.js';
+import { createVerifiedPageReceipt, selectVerifiedPage, validateVerifiedPageReceipt, } from '../internal/render-proof.js';
 // ---------------------------------------------------------------------------
 // S3 content provider — reads compiled content files from S3
 // ---------------------------------------------------------------------------
@@ -23,29 +24,21 @@ export class S3ContentProvider {
         return await this.getJSON(manifest.siteConfigRef);
     }
     async getPage(route) {
-        const manifest = await this.manifest();
-        const normalized = normalizeRoute(route);
-        const entry = Object.values(manifest.routes).find((candidate) => normalizeRoute(candidate.path) === normalized);
-        if (!entry) {
-            throw new PageNotFoundError(route);
-        }
-        try {
-            return await this.getJSON(entry.payloadRef);
-        }
-        catch (error) {
-            throw new PageNotFoundError(route, error);
-        }
+        return (await this.#selectPage({
+            route,
+            contentRef: '',
+            contentRefPresent: false,
+            variantKey: '',
+            variantKeyPresent: false,
+        })).page;
     }
     /**
-     * getPageByRef serves the exact payload the edge selected (the
-     * X-Aci-Content-Ref contract): base page or variant. Only refs the
-     * release manifest declares are served — the header names published
-     * content, it cannot address arbitrary keys.
+     * getPageByRef serves an exact payload the manifest declares. The stricter
+     * route-bound selection used by server rendering stays package-internal.
      */
     async getPageByRef(payloadRef) {
         const manifest = await this.manifest();
-        const known = Object.values(manifest.routes).some((entry) => entry.payloadRef === payloadRef ||
-            Object.values(entry.variants ?? {}).some((variant) => variant.payloadRef === payloadRef));
+        const known = Object.values(manifest.routes).some((entry) => routeContainsRef(entry, payloadRef));
         if (!known) {
             throw new PageNotFoundError(payloadRef);
         }
@@ -56,6 +49,20 @@ export class S3ContentProvider {
             throw new PageNotFoundError(payloadRef, error);
         }
     }
+    /** @internal */
+    async [selectVerifiedPage](request) {
+        const selection = await this.#selectPage(request, request.releaseId);
+        return Object.freeze({
+            page: selection.page,
+            receipt: createVerifiedPageReceipt({
+                releaseId: request.releaseId,
+                route: selection.route,
+                contentRef: selection.contentRef,
+                contentSha256: selection.contentSha256,
+                variantKey: selection.variantKey,
+            }),
+        });
+    }
     async getFragment(id) {
         const manifest = await this.manifest();
         const entry = manifest.fragments[id];
@@ -92,6 +99,149 @@ export class S3ContentProvider {
     async getJSON(key) {
         return await getS3JSON(joinKey(this.config.keyPrefix, key), this.config, this.#client);
     }
+    async #selectPage(request, releaseId) {
+        if (request.variantKeyPresent && !request.contentRefPresent) {
+            throw pageIntegrityError('variant header requires a content ref');
+        }
+        const manifest = await this.manifest();
+        const normalized = normalizeRoute(request.route);
+        const routeMatches = Object.values(manifest.routes).filter((candidate) => normalizeRoute(candidate.path) === normalized);
+        if (routeMatches.length === 0) {
+            if (request.contentRefPresent) {
+                const elsewhere = Object.values(manifest.routes)
+                    .some((candidate) => routeContainsRef(candidate, request.contentRef));
+                const reason = elsewhere ? 'cross-route content ref' : 'undeclared route content ref';
+                throw pageIntegrityError(`${reason}: ${request.contentRef}`);
+            }
+            throw new PageNotFoundError(request.route);
+        }
+        if (routeMatches.length !== 1) {
+            throw pageIntegrityError(`route ${normalized} is ambiguous`);
+        }
+        const entry = routeMatches[0];
+        const route = normalizeRoute(entry.path);
+        const tuples = [
+            {
+                contentRef: entry.payloadRef,
+                digest: entry.digest,
+                variantKey: '',
+                isVariant: false,
+            },
+            ...Object.values(entry.variants ?? {}).map(pageTupleForVariant),
+        ];
+        let tuple;
+        if (!request.contentRefPresent) {
+            tuple = tuples[0];
+        }
+        else {
+            const matches = tuples.filter((candidate) => {
+                if (candidate.contentRef !== request.contentRef)
+                    return false;
+                if (!request.variantKeyPresent)
+                    return true;
+                return candidate.isVariant && candidate.variantKey === request.variantKey;
+            });
+            if (matches.length === 0) {
+                const elsewhere = Object.values(manifest.routes)
+                    .filter((candidate) => candidate !== entry)
+                    .some((candidate) => routeContainsRef(candidate, request.contentRef));
+                const reason = elsewhere ? 'cross-route content ref' : 'undeclared route content ref';
+                throw pageIntegrityError(`${reason}: ${request.contentRef}`);
+            }
+            if (matches.length !== 1) {
+                throw pageIntegrityError(`ambiguous route content ref: ${request.contentRef}`);
+            }
+            tuple = matches[0];
+        }
+        const digestMatch = /^sha256:([0-9a-f]{64})$/.exec(tuple.digest);
+        if (!digestMatch) {
+            throw pageIntegrityError(`invalid manifest digest for ${tuple.contentRef}`);
+        }
+        const contentSha256 = digestMatch[1];
+        if (releaseId !== undefined) {
+            validateVerifiedPageReceipt({
+                releaseId,
+                route,
+                contentRef: tuple.contentRef,
+                contentSha256,
+                variantKey: tuple.variantKey,
+            });
+        }
+        const key = joinManifestContentKey(this.config.keyPrefix, tuple.contentRef);
+        let response;
+        try {
+            response = await getS3Raw(key, this.config, this.#client);
+        }
+        catch (cause) {
+            throw pageIntegrityError(`fetch failed for ${tuple.contentRef}`, cause);
+        }
+        if (!response.ok) {
+            const detail = await safeResponseText(response);
+            throw pageIntegrityError(`fetch failed for ${tuple.contentRef} with status ${response.status}${detail ? `: ${detail}` : ''}`);
+        }
+        let bytes;
+        try {
+            bytes = new Uint8Array(await response.arrayBuffer());
+        }
+        catch (cause) {
+            throw pageIntegrityError(`response body failed for ${tuple.contentRef}`, cause);
+        }
+        const actualDigest = crypto.createHash('sha256').update(bytes).digest('hex');
+        if (actualDigest !== contentSha256) {
+            throw pageIntegrityError(`digest mismatch for ${tuple.contentRef}: got ${actualDigest}, want ${contentSha256}`);
+        }
+        let source = '';
+        try {
+            source = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        }
+        catch (cause) {
+            throw pageIntegrityError(`invalid UTF-8 for ${tuple.contentRef}`, cause);
+        }
+        let page;
+        try {
+            page = JSON.parse(source);
+        }
+        catch (cause) {
+            throw pageIntegrityError(`invalid JSON for ${tuple.contentRef}`, cause);
+        }
+        return Object.freeze({
+            page,
+            route,
+            contentRef: tuple.contentRef,
+            contentSha256,
+            variantKey: tuple.variantKey,
+        });
+    }
+}
+function pageTupleForVariant(variant) {
+    if (typeof variant.variantKey !== 'string' || variant.variantKey === '') {
+        throw pageIntegrityError('variant manifest tuple has an empty variant key');
+    }
+    return {
+        contentRef: variant.payloadRef,
+        digest: variant.digest,
+        variantKey: variant.variantKey,
+        isVariant: true,
+    };
+}
+function routeContainsRef(entry, contentRef) {
+    return entry.payloadRef === contentRef
+        || Object.values(entry.variants ?? {})
+            .some((variant) => variant.payloadRef === contentRef);
+}
+function pageIntegrityError(message, cause) {
+    const error = new Error(`ACI S3 page integrity error: ${message}`);
+    if (cause !== undefined)
+        error.cause = cause;
+    return error;
+}
+async function safeResponseText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '';
+    }
 }
 // ---------------------------------------------------------------------------
 // S3 fetch with AWS SigV4 signing
@@ -278,3 +428,7 @@ function joinKey(...parts) {
         .filter(Boolean)
         .join('/');
 }
+function joinManifestContentKey(prefix, contentRef) {
+    const normalizedPrefix = joinKey(prefix);
+    return normalizedPrefix ? `${normalizedPrefix}/${contentRef}` : contentRef;
+}

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

@@ -5,7 +5,6 @@ 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>;
@@ -13,7 +12,6 @@ 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,7 +1,6 @@
 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.45",
+  "version": "0.1.46",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -114,7 +114,7 @@
     }
   },
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json && node scripts/build-collect.mjs",
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json && node scripts/assert-render-proof-public-surface.mjs && node scripts/build-collect.mjs",
     "test": "node --import tsx --test \"src/**/*.test.ts\"",
     "build:collect": "node scripts/build-collect.mjs",
     "build:cli": "cd ../.. && ./scripts/build-cli.sh",

package/src/cli/compile-registry.mjs

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
-import { realpathSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import { ImageSchema } from '../types/image.ts';
 import { VideoSchema } from '../types/video.ts';
@@ -20,15 +19,14 @@ try {
   if (!globalThis.React) globalThis.React = React;
 } catch { /* react not available — component files without JSX will still work */ }
 
-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;
-  }
+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) {
@@ -432,10 +430,9 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
   const defs = {
     baseBlock: {
       type: 'object',
-      required: ['$type', 'id', 'component', 'props'],
+      required: ['id', 'component', 'props'],
       additionalProperties: true,
       properties: {
-        $type: { const: 'component' },
         id: { type: 'string', minLength: 1 },
         component: { type: 'string' },
         props: { type: 'object' },
@@ -744,14 +741,3 @@ 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,24 +19,21 @@
  * 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';
-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;
-  }
+
+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;
 }
 
 // ---------------------------------------------------------------------------
@@ -98,24 +95,6 @@ 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,
@@ -401,13 +380,6 @@ 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}"` });
@@ -478,14 +450,3 @@ 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/cli/verify-next-cdn-routes.mjs

@@ -71,6 +71,12 @@ checkMissing(
   'The root catch-all handles release-scoped rewrites. Do not create a separate __r route folder.',
 );
 
+checkMissing(
+  'platform-owned collect route is absent',
+  'src/app/collect/route.ts',
+  'ACI injects the reserved /collect function during Vercel Build Output composition; customer source must not own it.',
+);
+
 checkFile(
   'next.config uses withAci',
   'next.config.mjs',

package/src/types/block-ref.ts

@@ -9,7 +9,6 @@ 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()),
@@ -22,7 +21,6 @@ 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,18 +13,17 @@ 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: [
-          { $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' } }
+          { 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' } }
         ]
       }
     }

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

@@ -14,15 +14,14 @@ 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: [
-          { $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' } }
+          { 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' } }
         ]
       }
     }

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

@@ -14,7 +14,6 @@ export const sectionStoryFixtures: SectionStoryFixture[] = [
     storybookId: 'sections-home-hero--default',
     title: 'Home Hero',
     block: {
-      $type: 'component',
       id: 'fixture-home-hero',
       component: 'home_hero',
       props: {
@@ -23,7 +22,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,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": {
@@ -417,7 +411,6 @@ framework.
 ```json
 // .content/pages/home/_index.json (inside regions.main)
 {
-  "$type": "component",
   "id": "features",
   "component": "feature_showcase",
   "props": {
@@ -506,10 +499,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": {