@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ebaebc4

package/authoring/doctypes/parse.mjs

@@ -15,16 +15,18 @@ import {parseTemplate} from './template/parse.mjs';
 import {parseSchema} from './schema/parse.mjs';
 import {parseCommand} from './command/parse.mjs';
 import {parseEnum} from './enum/parse.mjs';
+import {parseNamespace} from './namespace/parse.mjs';
 import {parseLegacyDoc} from './legacy.mjs';
 
-/** @typedef {import('./types').ComponentDoc} ComponentDoc */
-/** @typedef {import('./types').HookDoc} HookDoc */
-/** @typedef {import('./types').FunctionDoc} FunctionDoc */
-/** @typedef {import('./types').ReferenceDoc} ReferenceDoc */
-/** @typedef {import('./types').TemplateDoc} TemplateDoc */
-/** @typedef {import('./types').SchemaDoc} SchemaDoc */
-/** @typedef {import('./types').CommandDoc} CommandDoc */
-/** @typedef {import('./types').EnumDoc} EnumDoc */
+/** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types.js').HookDoc} HookDoc */
+/** @typedef {import('./types.js').FunctionDoc} FunctionDoc */
+/** @typedef {import('./types.js').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('./types.js').TemplateDoc} TemplateDoc */
+/** @typedef {import('./types.js').SchemaDoc} SchemaDoc */
+/** @typedef {import('./types.js').CommandDoc} CommandDoc */
+/** @typedef {import('./types.js').EnumDoc} EnumDoc */
+/** @typedef {import('./types.js').NamespaceDoc} NamespaceDoc */
 
 /**
  * Validate an unknown loaded doc value into its typed shape, or throw.
@@ -34,7 +36,7 @@ import {parseLegacyDoc} from './legacy.mjs';
  *
  * @param {unknown} input
  * @param {string} [label]
- * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc}
+ * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc}
  */
 export function parseDoc(input, label = 'doc') {
   const type =
@@ -58,7 +60,11 @@ export function parseDoc(input, label = 'doc') {
       return parseCommand(input, label);
     case 'enum':
       return parseEnum(input, label);
-    default:
+    case 'namespace':
+      return parseNamespace(input, label);
+    case undefined:
       return parseLegacyDoc(input, label);
+    default:
+      throw new Error(`${label} has unsupported type ${JSON.stringify(type)}.`);
   }
 }

package/authoring/doctypes/parse.test.mjs

@@ -25,8 +25,18 @@ const goodComponent = {
   displayName: 'Widget',
   description: 'A small widget.',
   props: [
-    {name: 'label', type: 'string', description: 'Visible label.', required: true},
-    {name: 'size', type: "'sm' | 'md'", description: 'Control size.', default: "'md'"},
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Visible label.',
+      required: true,
+    },
+    {
+      name: 'size',
+      type: "'sm' | 'md'",
+      description: 'Control size.',
+      default: "'md'",
+    },
   ],
 };
 
@@ -35,7 +45,9 @@ const goodFunction = {
   name: 'useThing',
   displayName: 'useThing',
   description: 'A thing hook.',
-  params: [{name: 'input', type: 'string', description: 'The input.', required: true}],
+  params: [
+    {name: 'input', type: 'string', description: 'The input.', required: true},
+  ],
   returns: [{name: 'value', type: 'string', description: 'The result.'}],
 };
 
@@ -43,7 +55,11 @@ const goodGeneric = {
   type: 'generic',
   name: 'Theming',
   displayName: 'Theming',
+  title: 'Theming',
   description: 'How theming works.',
+  sections: [
+    {title: 'Overview', content: [{type: 'prose', text: 'Use a theme.'}]},
+  ],
 };
 
 /** Run parseDoc and return the thrown message (asserting it throws). */
@@ -101,6 +117,34 @@ describe('per-kind parsers (stamped format)', () => {
     expect(() => parseReference(goodGeneric)).not.toThrow();
   });
 
+  it('normalizes a migrated minimal generic doc to the public shape', () => {
+    expect(
+      parseReference({
+        type: 'generic',
+        name: 'Theming',
+        description: 'How theming works.',
+      }),
+    ).toMatchObject({
+      type: 'generic',
+      name: 'Theming',
+      title: 'Theming',
+      description: 'How theming works.',
+      sections: [],
+    });
+  });
+
+  it('rejects duplicate stable section IDs', () => {
+    expect(() =>
+      parseReference({
+        ...goodGeneric,
+        sections: [
+          {id: 'start', title: 'Start', content: []},
+          {id: 'start', title: 'Renamed start', content: []},
+        ],
+      }),
+    ).toThrow(/sections\.1\.id.*duplicate section id/u);
+  });
+
   it('keeps nested rich blobs loose (usage/theming/playground passthrough)', () => {
     expect(() =>
       parseComponent({
@@ -123,6 +167,16 @@ describe('per-kind parsers (stamped format)', () => {
     expect(parsed.parent).toBe('WidgetGroup');
     expect(parsed.relatedDocs).toEqual(['Gauge', 'useThing']);
   });
+
+  it('validates graph metadata on unstamped legacy docs', () => {
+    expect(() =>
+      parseDoc({name: 'Widget', props: [], placement: {parent: ''}}),
+    ).toThrow(/placement\.parent/u);
+    expect(() => parseDoc({name: 'Widget', props: [], aliases: [1]})).toThrow();
+    expect(() =>
+      parseDoc({name: 'Widget', props: [], audience: 'secret'}),
+    ).toThrow();
+  });
 });
 
 describe('parseDoc (load boundary, both formats)', () => {
@@ -175,6 +229,24 @@ describe('parseDoc (load boundary, both formats)', () => {
     expect(() => parseDoc(hook)).not.toThrow();
   });
 
+  it('accepts and validates the OLD loose reference-topic shape', () => {
+    const reference = {
+      name: 'theming',
+      title: 'Theming',
+      description: 'How theming works.',
+      sections: [
+        {id: 'start', title: 'Start', content: [{type: 'prose', text: 'Go.'}]},
+      ],
+    };
+    expect(parseDoc(reference)).toEqual(reference);
+    expect(() =>
+      parseDoc({
+        ...reference,
+        sections: [{title: 'Start', content: [{type: 'prose'}]}],
+      }),
+    ).toThrow();
+  });
+
   it('accepts BOTH parent and legacy subComponentOf', () => {
     const withParent = {name: 'A', parent: 'B', props: []};
     const withSubComponentOf = {
@@ -289,7 +361,9 @@ describe('loadComponentDoc (end-to-end load boundary)', () => {
         "  type: 'generic',",
         "  name: 'Theming',",
         "  displayName: 'Theming',",
+        "  title: 'Theming',",
         "  description: 'How theming works.',",
+        "  sections: [{title: 'Overview', content: [{type: 'prose', text: 'Use a theme.'}]}],",
         '};',
       ].join('\n'),
     );

package/authoring/doctypes/reference/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('../types.js').ReferenceDoc} ReferenceDoc */
 /**
  * Validate an unknown value as a stamped reference/topic doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {ReferenceDoc}
  */
 export function parseReference(input: unknown, label?: string): ReferenceDoc;
-export type ReferenceDoc = import("../types").ReferenceDoc;
+export type ReferenceDoc = import("../types.js").ReferenceDoc;

package/authoring/doctypes/reference/parse.mjs

@@ -9,7 +9,7 @@
 import {GenericDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('../types.js').ReferenceDoc} ReferenceDoc */
 
 /**
  * Validate an unknown value as a stamped reference/topic doc, or throw.
@@ -23,8 +23,11 @@ export function parseReference(input, label = 'reference doc') {
   if (!result.success) {
     throw new Error(formatZodError(label, result.error));
   }
-  // The schema is permissive (it also accepts legacy generic docs), so it is
-  // deliberately looser than the rich public type; cast through unknown at this
-  // validated boundary.
-  return /** @type {ReferenceDoc} */ (/** @type {unknown} */ (result.data));
+  const doc = result.data;
+  return /** @type {ReferenceDoc} */ ({
+    ...doc,
+    title: doc.title ?? doc.displayName ?? doc.name,
+    description: doc.description ?? '',
+    sections: doc.sections ?? [],
+  });
 }

package/authoring/doctypes/reference/reference.doc.mjs

@@ -55,7 +55,7 @@ export const doc = {
       name: 'replaces',
       type: 'string',
       description:
-        "Name of an existing topic this doc takes the place of. Authored by an integration that serves its own guide instead of the built-in one: on a doc of the same name it swaps the content, and on a doc of another name it also leaves the old name as an alias so `astryx docs <old>` still resolves. Exclusive with `extends`.",
+        'Name of an existing topic this doc takes the place of. Authored by an integration that serves its own guide instead of the built-in one: on a doc of the same name it swaps the content, and on a doc of another name it also leaves the old name as an alias so `astryx docs <old>` still resolves. Exclusive with `extends`.',
       example: "'getting-started'",
     },
     {
@@ -72,6 +72,12 @@ export const doc = {
         'Ordered sections that make up the doc. Each becomes an h2 in full output and can be retrieved via `astryx docs <topic> <section>`.',
       required: true,
       fields: [
+        {
+          name: 'sections[].id',
+          type: 'string',
+          description:
+            'Stable section anchor. New docs should set this instead of relying on a mutable title.',
+        },
         {
           name: 'sections[].title',
           type: 'string',
@@ -89,7 +95,7 @@ export const doc = {
           name: 'sections[].content',
           type: 'ReferenceContentBlock[]',
           description:
-            'Ordered content blocks. Mix prose, code, tables, and lists freely.',
+            'Ordered content blocks: prose, heading, code, table, list, and token-ref. workflow, collection, and reference are declared for the docs graph and parse, but a topic that uses one fails to load until the docs graph ships.',
           required: true,
         },
         {
@@ -134,7 +140,11 @@ export const docs = {
   notes: [
     {
       type: 'prose',
-      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, a discriminated union. New block types can be added without breaking existing docs. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
+      text: 'A stamped generic doc without `title`, `description` or `sections` still loads, as older codemod output does; its title falls back to `displayName` or `name`. Without a description and sections it is not a usable topic, and `astryx doctor` reports it.',
+    },
+    {
+      type: 'prose',
+      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, a discriminated union. workflow, collection, and reference are declared for the docs graph: they parse, but topic loading rejects them until the docs graph ships. choice, callout, and checklist remain invalid. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
     },
     {
       type: 'code',
@@ -146,7 +156,10 @@ export const docs = {
   | { type: 'code'; lang: string; code: string; label?: string }
   | { type: 'table'; headers: string[]; rows: string[][] }
   | { type: 'list'; style: 'ordered' | 'unordered' | 'do' | 'dont'; items: string[] }
-  | { type: 'token-ref'; topic: string; section: string };`,
+  | { type: 'token-ref'; topic: string; section: string }
+  | { type: 'workflow'; title?: string; steps: WorkflowStep[] }
+  | { type: 'collection'; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
+  | { type: 'reference'; target: string; projection?: {fields?: string[]; sections?: string[]} };`,
     },
     {
       type: 'prose',

package/authoring/doctypes/reference/type.ts

@@ -4,10 +4,48 @@
  * @file Reference/topic doc types.
  */
 
+import type {AuthoredDocGraphFields} from '../base/type.js';
+
+/** One step in a renderer-neutral workflow. */
+export interface WorkflowStep {
+  title: string;
+  description?: string;
+  /** Stable doc references that supply detail for this step. */
+  references?: string[];
+}
+
+/** Ordered procedural guidance. */
+export interface WorkflowDocBlock {
+  type: 'workflow';
+  title?: string;
+  steps: WorkflowStep[];
+}
+
+/** A generated view over docs placed in one namespace slot. */
+export interface CollectionDocBlock {
+  type: 'collection';
+  title?: string;
+  source: {slot: string};
+  presentation?: 'list' | 'cards' | 'compact';
+  whenEmpty?: 'show' | 'omit';
+}
+
+/** A bounded projection of one canonical doc. */
+export interface ReferenceDocBlock {
+  type: 'reference';
+  target: string;
+  projection?: {
+    fields?: string[];
+    sections?: string[];
+  };
+  presentation?: 'summary' | 'compact' | 'full';
+}
+
 /**
- * A content block within a reference doc section.
- * Ordered array of these makes up a section's content.
- * New block types can be added without breaking existing docs.
+ * A content block within a reference doc section or namespace.
+ * Ordered arrays of these blocks form renderer-neutral documentation content.
+ * A new semantic kind must ship with every renderer or fail visibly at a legacy
+ * reader boundary until that renderer is available.
  *
  * @example
  * ```
@@ -17,6 +55,9 @@
  * { type: 'table', headers: ['Token', 'Value'], rows: [['--spacing-4', '16px']] }
  * { type: 'list', style: 'do', items: ['Use semantic tokens'] }
  * { type: 'token-ref', topic: 'tokens', section: 'Color Tokens' }
+ * { type: 'workflow', steps: [{title: 'Validate', references: ['command:doctor']}] }
+ * { type: 'collection', source: {slot: 'guides'}, presentation: 'cards' }
+ * { type: 'reference', target: 'schema:integration', projection: {fields: ['docs']} }
  * ```
  */
 export type ReferenceContentBlock =
@@ -39,7 +80,10 @@ export type ReferenceContentBlock =
       topic: string;
       /** Section title to pull from that topic. e.g. `'Color Tokens'` */
       section: string;
-    };
+    }
+  | WorkflowDocBlock
+  | CollectionDocBlock
+  | ReferenceDocBlock;
 
 /**
  * A reference documentation file (.doc.mjs).
@@ -54,7 +98,7 @@ export type ReferenceContentBlock =
  *   /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} *\/
  *   export const docs = { ... };
  */
-export interface ReferenceDoc {
+export interface ReferenceDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant for the stamped default-export format
    *  (`export default { type: 'generic', ... }`). Optional: legacy
    *  `export const docs = {...}` docs omit it. The value stays `'generic'`
@@ -95,6 +139,8 @@ export interface ReferenceDoc {
  * and can be individually retrieved via `astryx docs <topic> <section>`.
  */
 export interface ReferenceSection {
+  /** Stable section anchor. New docs should set this instead of relying on title. */
+  id?: string;
   /** Section title, e.g. "Spacing Tokens", "Light/Dark Mode" */
   title: string;
   /** Navigation category ('guide' | 'foundations'). Mirrors the parent doc's

package/authoring/doctypes/schema/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').SchemaDoc} SchemaDoc */
+/** @typedef {import('../types.js').SchemaDoc} SchemaDoc */
 /**
  * Validate an unknown value as a stamped schema doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {SchemaDoc}
  */
 export function parseSchema(input: unknown, label?: string): SchemaDoc;
-export type SchemaDoc = import("../types").SchemaDoc;
+export type SchemaDoc = import("../types.js").SchemaDoc;

package/authoring/doctypes/schema/parse.mjs

@@ -8,7 +8,7 @@
 import {SchemaDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').SchemaDoc} SchemaDoc */
+/** @typedef {import('../types.js').SchemaDoc} SchemaDoc */
 
 /**
  * Validate an unknown value as a stamped schema doc, or throw.

package/authoring/doctypes/schema/type.ts

@@ -6,7 +6,8 @@
  * response envelope). Colocated as a `.doc.mjs` next to the schema it describes.
  */
 
-import type {ReferenceContentBlock} from '../reference/type';
+import type {AuthoredDocGraphFields} from '../base/type.js';
+import type {ReferenceContentBlock} from '../reference/type.js';
 
 /**
  * One documented field of a schema. Object fields nest via `fields`, so a whole
@@ -37,7 +38,7 @@ export interface SchemaFieldDoc {
  *   /\*\* @type {import('@astryxdesign/cli/authoring').SchemaDoc} \*\/
  *   export const doc = { type: 'schema', name: 'config', ... };
  */
-export interface SchemaDoc {
+export interface SchemaDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant. */
   type?: 'schema';
   /** URL-safe identifier, used as the docs slug within its namespace. */

package/authoring/doctypes/template/parse.d.mts

@@ -11,4 +11,95 @@
  * @returns {TemplateDoc}
  */
 export function parseTemplate(input: unknown, label?: string): TemplateDoc;
-export type TemplateDoc = import("../types").TemplateDoc;
+export type TemplateDoc = import("../types.js").TemplateDoc;
+export type PageTemplateDoc = import("./type.js").PageTemplateDoc;
+export type BlockTemplateDoc = import("./type.js").BlockTemplateDoc;
+/**
+ * Templates as they load. Integration templates already published omit
+ * `displayName` and `aspectRatio` and group themselves under their own
+ * `category`, so the loader accepts those (template discovery falls back to an
+ * aspect ratio of 1). The published types keep asking authors for all three.
+ */
+export type LoadedPageTemplateDoc = Omit<PageTemplateDoc, "displayName" | "category"> & {
+    displayName?: string;
+    category?: string;
+};
+/**
+ * Templates as they load. Integration templates already published omit
+ * `displayName` and `aspectRatio` and group themselves under their own
+ * `category`, so the loader accepts those (template discovery falls back to an
+ * aspect ratio of 1). The published types keep asking authors for all three.
+ */
+export type LoadedBlockTemplateDoc = Omit<BlockTemplateDoc, "displayName" | "aspectRatio" | "category"> & {
+    displayName?: string;
+    aspectRatio?: number;
+    category?: string;
+};
+export type _PageTemplateDocDriftLock = import("../../_shared/contract.js").Expect<import("../../_shared/contract.js").MutuallyAssignable<import("../../_shared/contract.js").NamedFields<z.infer<typeof pageTemplateSchema>>, import("../../_shared/contract.js").NamedFields<LoadedPageTemplateDoc>>>;
+export type _BlockTemplateDocDriftLock = import("../../_shared/contract.js").Expect<import("../../_shared/contract.js").MutuallyAssignable<import("../../_shared/contract.js").NamedFields<z.infer<typeof blockTemplateSchema>>, import("../../_shared/contract.js").NamedFields<LoadedBlockTemplateDoc>>>;
+import { z } from 'zod';
+declare const pageTemplateSchema: z.ZodObject<{
+    type: z.ZodLiteral<"page">;
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    componentsUsed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    preview: z.ZodOptional<z.ZodObject<{
+        image: z.ZodOptional<z.ZodString>;
+        aspectRatio: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    isReady: z.ZodOptional<z.ZodBoolean>;
+    scaffold: z.ZodOptional<z.ZodBoolean>;
+    isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+    registry: z.ZodOptional<z.ZodObject<{
+        slug: z.ZodOptional<z.ZodString>;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
+}, z.core.$strict>;
+declare const blockTemplateSchema: z.ZodObject<{
+    type: z.ZodLiteral<"block">;
+    exampleFor: z.ZodOptional<z.ZodString>;
+    alsoExampleFor: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    alsoShowcaseFor: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aspectRatio: z.ZodOptional<z.ZodNumber>;
+    scale: z.ZodOptional<z.ZodNumber>;
+    isShowcase: z.ZodOptional<z.ZodBoolean>;
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    componentsUsed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    preview: z.ZodOptional<z.ZodObject<{
+        image: z.ZodOptional<z.ZodString>;
+        aspectRatio: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    isReady: z.ZodOptional<z.ZodBoolean>;
+    scaffold: z.ZodOptional<z.ZodBoolean>;
+    isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+    registry: z.ZodOptional<z.ZodObject<{
+        slug: z.ZodOptional<z.ZodString>;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
+}, z.core.$strict>;
+export {};

package/authoring/doctypes/template/parse.mjs

@@ -9,9 +9,12 @@
  */
 
 import {z} from 'zod';
+import {AuthoredDocGraphFields} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').TemplateDoc} TemplateDoc */
+/** @typedef {import('../types.js').TemplateDoc} TemplateDoc */
+/** @typedef {import('./type.js').PageTemplateDoc} PageTemplateDoc */
+/** @typedef {import('./type.js').BlockTemplateDoc} BlockTemplateDoc */
 
 const previewSchema = z
   .object({
@@ -37,9 +40,10 @@ const registryIdentitySchema = z
   .strict();
 
 const baseTemplateFields = {
+  ...AuthoredDocGraphFields,
   name: z.string().min(1, 'name is required'),
   displayName: z.string().min(1).optional(),
-  description: z.string().min(1, 'description is required'),
+  description: z.string().min(1, 'description is required').optional(),
   category: z.string().optional(),
   componentsUsed: z.array(z.string()).optional(),
   preview: previewSchema.optional(),
@@ -65,6 +69,36 @@ const blockTemplateSchema = z
   })
   .strict();
 
+/**
+ * Templates as they load. Integration templates already published omit
+ * `displayName` and `aspectRatio` and group themselves under their own
+ * `category`, so the loader accepts those (template discovery falls back to an
+ * aspect ratio of 1). The published types keep asking authors for all three.
+ *
+ * @typedef {Omit<PageTemplateDoc, 'displayName' | 'category'>
+ *   & {displayName?: string, category?: string}} LoadedPageTemplateDoc
+ * @typedef {Omit<BlockTemplateDoc, 'displayName' | 'aspectRatio' | 'category'>
+ *   & {displayName?: string, aspectRatio?: number, category?: string}} LoadedBlockTemplateDoc
+ */
+
+/**
+ * @typedef {import('../../_shared/contract.js').Expect<
+ *   import('../../_shared/contract.js').MutuallyAssignable<
+ *     import('../../_shared/contract.js').NamedFields<z.infer<typeof pageTemplateSchema>>,
+ *     import('../../_shared/contract.js').NamedFields<LoadedPageTemplateDoc>
+ *   >
+ * >} _PageTemplateDocDriftLock
+ */
+
+/**
+ * @typedef {import('../../_shared/contract.js').Expect<
+ *   import('../../_shared/contract.js').MutuallyAssignable<
+ *     import('../../_shared/contract.js').NamedFields<z.infer<typeof blockTemplateSchema>>,
+ *     import('../../_shared/contract.js').NamedFields<LoadedBlockTemplateDoc>
+ *   >
+ * >} _BlockTemplateDocDriftLock
+ */
+
 const templateEnvelopeSchema = z
   .discriminatedUnion('type', [pageTemplateSchema, blockTemplateSchema])
   .superRefine((template, context) => {

package/authoring/doctypes/template/parse.test.mjs

@@ -112,8 +112,14 @@ describe('parseTemplate (load boundary)', () => {
     expect(reason({type: 'page', description: 'x'})).toContain('name');
   });
 
-  it('rejects a missing description', () => {
-    expect(reason({type: 'page', name: 'x'})).toContain('description');
+  it('accepts an omitted description and rejects an empty one when present', () => {
+    expect(parseTemplate({type: 'page', name: 'x'})).toEqual({
+      type: 'page',
+      name: 'x',
+    });
+    expect(reason({type: 'page', name: 'x', description: ''})).toContain(
+      'description',
+    );
   });
 
   it('rejects an empty-string name', () => {

package/authoring/doctypes/template/template.doc.mjs

@@ -148,6 +148,10 @@ export const doc = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: 'When it loads, a template may leave out `displayName` and `aspectRatio` and use its own `category`, as integration templates already published do; a block with no `aspectRatio` previews at 1. Write to the type anyway; it is the contract.',
+    },
     {
       type: 'prose',
       text: "TemplateDoc is a discriminated union keyed by `type`. Set `type: 'page'` for a full page template. Set `type: 'block'` for an editable composition; add `exampleFor` only when one component owns the example.",

package/authoring/doctypes/template/type.ts

@@ -4,9 +4,12 @@
  * @file Template doc types.
  */
 
-import type {RegistryDocIdentity} from '../base/type';
+import type {
+  AuthoredDocGraphFields,
+  RegistryDocIdentity,
+} from '../base/type.js';
 
-export interface BaseTemplateDoc {
+export interface BaseTemplateDoc extends AuthoredDocGraphFields {
   /** Identifier name for the template. For block templates this matches
    *  the React component import name (e.g. `"ChatMessageMetadata"`); for
    *  page templates it's a human-readable label that doubles as the

package/authoring/doctypes/types.ts

@@ -7,12 +7,13 @@
  * behind `@astryxdesign/cli/authoring`.
  */
 
-export type * from './base/type';
-export type * from './component/type';
-export type * from './hook/type';
-export type * from './function/type';
-export type * from './reference/type';
-export type * from './template/type';
-export type * from './schema/type';
-export type * from './command/type';
-export type * from './enum/type';
+export type * from './base/type.js';
+export type * from './component/type.js';
+export type * from './hook/type.js';
+export type * from './function/type.js';
+export type * from './reference/type.js';
+export type * from './namespace/type.js';
+export type * from './template/type.js';
+export type * from './schema/type.js';
+export type * from './command/type.js';
+export type * from './enum/type.js';