@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9e4c545

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

@@ -12,7 +12,9 @@ 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({
@@ -67,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/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,7 +4,10 @@
  * @file Template doc types.
  */
 
-import type {AuthoredDocGraphFields, RegistryDocIdentity} from '../base/type';
+import type {
+  AuthoredDocGraphFields,
+  RegistryDocIdentity,
+} from '../base/type.js';
 
 export interface BaseTemplateDoc extends AuthoredDocGraphFields {
   /** Identifier name for the template. For block templates this matches

package/authoring/doctypes/types.ts

@@ -7,13 +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 './namespace/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';

package/authoring/gap-report/parse.d.mts

@@ -2,8 +2,8 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>
  * >} _GapReportReceiptDriftLock
  */
 /**
@@ -25,23 +25,23 @@ export function parseGapReportHandler(input: unknown, label?: string): GapReport
  * @returns {GapReportHandlerReceipt | null}
  */
 export function parseGapReportReceipt(input: unknown): GapReportHandlerReceipt | null;
-export type _GapReportReceiptDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>>;
-export type GapReportHandler = import("./type").GapReportHandler;
-export type GapReportHandlerReceipt = import("./type").GapReportHandlerReceipt;
+export type _GapReportReceiptDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>>;
+export type GapReportHandler = import("./type.js").GapReportHandler;
+export type GapReportHandlerReceipt = import("./type.js").GapReportHandlerReceipt;
 /**
  * Compile-time drift-lock: the sealed schema must infer EXACTLY the public
  * {@link GapReportHandler} type. If they drift, `MutuallyAssignable` becomes
  * `false` and `Expect<false>` fails `tsconfig.authoring-contract.json`.
  */
-export type _GapReportHandlerDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>>;
+export type _GapReportHandlerDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>>;
 import { z } from 'zod';
 /**
  * Compile-time drift-lock: the sealed schema must infer EXACTLY the public
  * {@link GapReportHandler} type. If they drift, `MutuallyAssignable` becomes
  * `false` and `Expect<false>` fails `tsconfig.authoring-contract.json`.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>
  * >} _GapReportHandlerDriftLock
  */
 declare const receiptSchema: z.ZodObject<{
@@ -58,6 +58,6 @@ declare const handlerSchema: z.ZodObject<{
         public: "public";
         internal: "internal";
     }>;
-    handle: z.ZodType<(report: import("./type").GapReport, context: import("./type").GapReportHandlerContext) => import("./type").GapReportHandlerReceipt | Promise<import("./type").GapReportHandlerReceipt>, any, z.core.$ZodTypeInternals<(report: import("./type").GapReport, context: import("./type").GapReportHandlerContext) => import("./type").GapReportHandlerReceipt | Promise<import("./type").GapReportHandlerReceipt>, any>>;
+    handle: z.ZodType<(report: import("./type.js").GapReport, context: import("./type.js").GapReportHandlerContext) => import("./type.js").GapReportHandlerReceipt | Promise<import("./type.js").GapReportHandlerReceipt>, any, z.core.$ZodTypeInternals<(report: import("./type.js").GapReport, context: import("./type.js").GapReportHandlerContext) => import("./type.js").GapReportHandlerReceipt | Promise<import("./type.js").GapReportHandlerReceipt>, any>>;
 }, z.core.$strict>;
 export {};

package/authoring/gap-report/parse.mjs

@@ -13,8 +13,8 @@
 import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./type').GapReportHandler} GapReportHandler */
-/** @typedef {import('./type').GapReportHandlerReceipt} GapReportHandlerReceipt */
+/** @typedef {import('./type.js').GapReportHandler} GapReportHandler */
+/** @typedef {import('./type.js').GapReportHandlerReceipt} GapReportHandlerReceipt */
 
 // Typed z.custom so z.infer reproduces the real function type, matching the
 // pattern used by the debug handler and post-codemod hook parsers.
@@ -36,8 +36,8 @@ const handlerSchema = z
  * {@link GapReportHandler} type. If they drift, `MutuallyAssignable` becomes
  * `false` and `Expect<false>` fails `tsconfig.authoring-contract.json`.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>
  * >} _GapReportHandlerDriftLock
  */
 
@@ -50,8 +50,8 @@ const receiptSchema = z
   .strict();
 
 /**
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>
  * >} _GapReportReceiptDriftLock
  */
 

package/authoring/gap-report/type.ts

@@ -14,7 +14,7 @@
  * gap-report handlers.
  */
 
-import type {DebugInvocationSource} from '../debug/type';
+import type {DebugInvocationSource} from '../debug/type.js';
 
 /** Supported gap-report categories. */
 export type GapReportCategory =

package/authoring/identity/identity.doc.mjs

@@ -12,8 +12,9 @@ export const doc = {
   displayName: 'Provider and artifact identity',
   namespace: 'authoring',
   description:
-    'Separates stable provider/artifact identity from package instances and runtime lifecycle state.',
-  appliesTo: 'Compiler inputs, manifests, search, Build, and Doctor',
+    'Separates stable provider/artifact identity from package instances and runtime lifecycle state. providerId is in use today: an integration manifest may declare it, and Doctor and every command report two packages that claim one. The artifact, doc, instance, and compiler-input identities are defined for the docs graph, which is not built yet, and no command reads them.',
+  appliesTo:
+    'Integration manifests and provider conflicts today; the docs graph once it ships',
   fields: [
     {
       name: 'ProviderId',

package/authoring/identity/type.ts

@@ -8,16 +8,16 @@
  * artifact ID stays stable across those instances.
  */
 
-import type {AuthoredDocKind} from '../doctypes/base/type';
-import type {CommandDoc} from '../doctypes/command/type';
-import type {ComponentDoc} from '../doctypes/component/type';
-import type {EnumDoc} from '../doctypes/enum/type';
-import type {FunctionDoc} from '../doctypes/function/type';
-import type {HookDoc} from '../doctypes/hook/type';
-import type {NamespaceDoc} from '../doctypes/namespace/type';
-import type {ReferenceDoc} from '../doctypes/reference/type';
-import type {SchemaDoc} from '../doctypes/schema/type';
-import type {TemplateDoc} from '../doctypes/template/type';
+import type {AuthoredDocKind} from '../doctypes/base/type.js';
+import type {CommandDoc} from '../doctypes/command/type.js';
+import type {ComponentDoc} from '../doctypes/component/type.js';
+import type {EnumDoc} from '../doctypes/enum/type.js';
+import type {FunctionDoc} from '../doctypes/function/type.js';
+import type {HookDoc} from '../doctypes/hook/type.js';
+import type {NamespaceDoc} from '../doctypes/namespace/type.js';
+import type {ReferenceDoc} from '../doctypes/reference/type.js';
+import type {SchemaDoc} from '../doctypes/schema/type.js';
+import type {TemplateDoc} from '../doctypes/template/type.js';
 
 declare const providerIdBrand: unique symbol;
 declare const artifactIdBrand: unique symbol;

package/authoring/index.d.ts

@@ -23,18 +23,18 @@
 // ═══════════════════════════════════════════════════════════════════════
 // AUTHOR THESE — each is the default export of one authored file.
 // ═══════════════════════════════════════════════════════════════════════
-export type {ComponentDoc} from './doctypes/types'; //   Button.doc.{ts,mjs}
-export type {HookDoc} from './doctypes/types'; //         useToast.doc.{ts,mjs}
-export type {FunctionDoc} from './doctypes/types'; //     search.doc.mjs (hook | api)
-export type {ReferenceDoc} from './doctypes/types'; //    theming.doc.{ts,mjs}
-export type {TemplateDoc} from './doctypes/types'; //     Foo.template.{ts,mjs}
-export type {SchemaDoc} from './doctypes/types'; //       config.doc.mjs (object shape)
-export type {CommandDoc} from './doctypes/types'; //      search.doc.mjs (CLI command)
-export type {EnumDoc} from './doctypes/types'; //         error-codes.doc.mjs (vocabulary)
-export type {NamespaceDoc} from './doctypes/types'; //    cli.doc.mjs (hierarchy)
-export type {AstryxConfig} from './config/type'; //       astryx.config.{ts,mjs}
-export type {DebugEvent} from './debug/type'; //          one recorded CLI run
-export type {AstryxIntegration} from './integration/type'; // astryx.integration.{ts,mjs}
+export type {ComponentDoc} from './doctypes/types.js'; //   Button.doc.{ts,mjs}
+export type {HookDoc} from './doctypes/types.js'; //         useToast.doc.{ts,mjs}
+export type {FunctionDoc} from './doctypes/types.js'; //     search.doc.mjs (hook | api)
+export type {ReferenceDoc} from './doctypes/types.js'; //    theming.doc.{ts,mjs}
+export type {TemplateDoc} from './doctypes/types.js'; //     Foo.template.{ts,mjs}
+export type {SchemaDoc} from './doctypes/types.js'; //       config.doc.mjs (object shape)
+export type {CommandDoc} from './doctypes/types.js'; //      search.doc.mjs (CLI command)
+export type {EnumDoc} from './doctypes/types.js'; //         error-codes.doc.mjs (vocabulary)
+export type {NamespaceDoc} from './doctypes/types.js'; //    cli.doc.mjs (hierarchy)
+export type {AstryxConfig} from './config/type.js'; //       astryx.config.{ts,mjs}
+export type {DebugEvent} from './debug/type.js'; //          one recorded CLI run
+export type {AstryxIntegration} from './integration/type.js'; // astryx.integration.{ts,mjs}
 export type {
   GapReportHandler,
   GapReportHandlerContext,
@@ -42,8 +42,8 @@ export type {
   GapReportCategory,
   GapReportTarget,
   GapReportHandlerReceipt,
-} from './gap-report/type'; // gap-report handler contract
-export type {AstryxCodemod, AstryxConfigCodemod} from './codemod/type'; // codemods/*
+} from './gap-report/type.js'; // gap-report handler contract
+export type {AstryxCodemod, AstryxConfigCodemod} from './codemod/type.js'; // codemods/*
 
 // ═══════════════════════════════════════════════════════════════════════
 // PARSERS — the CLI's load boundary (types come from each parser's JSDoc).
@@ -87,7 +87,7 @@ export type {
   AuthoredDocSnapshot,
   AuthoredDocSource,
   AuthoredDocEntry,
-} from './identity/type';
+} from './identity/type.js';
 export type {
   // shared graph
   AuthoredDocKind,
@@ -151,8 +151,8 @@ export type {
   CommandExampleDoc,
   // enum
   EnumMemberDoc,
-} from './doctypes/types';
-export type {PostCodemodHook, DebugConfig} from './config/type';
+} from './doctypes/types.js';
+export type {PostCodemodHook, DebugConfig} from './config/type.js';
 export type {
   // debug
   DebugSchemaVersion,
@@ -165,11 +165,11 @@ export type {
   DebugEventEnv,
   DebugEventProject,
   DebugEventHandler,
-} from './debug/type';
+} from './debug/type.js';
 export type {
   AstryxCodemodDef,
   AstryxConfigCodemodDef,
   AstryxCodemodFile,
   AstryxCodemodApi,
   AstryxCodemodTransform,
-} from './codemod/type';
+} from './codemod/type.js';

package/authoring/integration/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('./type').AstryxIntegration} AstryxIntegration */
+/** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 /**
  * Validate an unknown value as an Astryx integration manifest, or throw.
  *
@@ -14,4 +14,4 @@
  * @returns {AstryxIntegration}
  */
 export function parseIntegration(input: unknown, label?: string): AstryxIntegration;
-export type AstryxIntegration = import("./type").AstryxIntegration;
+export type AstryxIntegration = import("./type.js").AstryxIntegration;

package/authoring/integration/parse.mjs

@@ -14,7 +14,7 @@
 import {formatZodError} from '../_shared/errors.mjs';
 import {integrationSchema} from './schema.mjs';
 
-/** @typedef {import('./type').AstryxIntegration} AstryxIntegration */
+/** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 
 /**
  * Validate an unknown value as an Astryx integration manifest, or throw.

package/authoring/integration/schema.d.mts

@@ -55,8 +55,8 @@ export const integrationSchema: z.ZodObject<{
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
  * >} _IntegrationDriftLock
  */
 /**
@@ -69,9 +69,9 @@ export const integrationSchema: z.ZodObject<{
  * @type {string[]}
  */
 export const KNOWN_INTEGRATION_KEYS: string[];
-export type AstryxIntegration = import("./type").AstryxIntegration;
+export type AstryxIntegration = import("./type.js").AstryxIntegration;
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  */
-export type _IntegrationDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").Equal<z.infer<typeof integrationSchema>, AstryxIntegration>>;
+export type _IntegrationDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof integrationSchema>, AstryxIntegration>>;
 import { z } from 'zod';

package/authoring/integration/schema.mjs

@@ -16,7 +16,7 @@
 import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./type').AstryxIntegration} AstryxIntegration */
+/** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 
 const MAX_AGENT_DOC_LINES = 8;
 const MAX_AGENT_DOC_LINE_CODE_POINTS = 240;
@@ -121,8 +121,8 @@ export function parseAgentDocsField(input, label) {
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
  * >} _IntegrationDriftLock
  */
 

package/authoring/integration/type.ts

@@ -66,4 +66,4 @@ export type {
   GapReportCategory,
   GapReportTarget,
   GapReportHandlerReceipt,
-} from '../gap-report/type';
+} from '../gap-report/type.js';

package/foundation/discovery/authoring-self-docs.test.mjs

@@ -9,7 +9,14 @@ import {
   buildAuthoringTopic,
   discoverAuthoringSelfDocSources,
 } from './authoring-self-docs.mjs';
-import {problemsInTopic} from './docs-discovery.mjs';
+import {
+  GRAPH_BLOCK_TYPES,
+  GRAPH_ONLY_FIELDS,
+  problemsInTopic,
+} from './docs-discovery.mjs';
+import {doc as graphFieldsDoc} from '../../authoring/doctypes/base/graph-fields.doc.mjs';
+import {doc as namespaceDoc} from '../../authoring/doctypes/namespace/namespace.doc.mjs';
+import {doc as referenceDoc} from '../../authoring/doctypes/reference/reference.doc.mjs';
 import {docs} from '../../api/docs/docs.mjs';
 
 const SLOW = 60_000;
@@ -37,14 +44,58 @@ describe('authoring self-docs', () => {
     expect(topic.sections).toHaveLength(AUTHORING_SELF_DOCS.length);
   });
 
-  it('is readable progressively through the docs API', async () => {
-    const index = await docs('authoring', undefined, {index: true});
-    expect(index.type).toBe('docs.index');
-    expect(index.data.sections.map(s => s.id)).toContain('integration');
-    const section = await docs('authoring', 'integration');
-    expect(section.data.title).toBe('Astryx Integration');
-    expect(section.data.content.some(block => block.type === 'table')).toBe(true);
-  }, SLOW);
+  it(
+    'is readable progressively through the docs API',
+    async () => {
+      const index = await docs('authoring', undefined, {index: true});
+      expect(index.type).toBe('docs.index');
+      expect(index.data.sections.map(s => s.id)).toContain('integration');
+      const section = await docs('authoring', 'integration');
+      expect(section.data.title).toBe('Astryx Integration');
+      expect(section.data.content.some(block => block.type === 'table')).toBe(
+        true,
+      );
+    },
+    SLOW,
+  );
+});
+
+describe('what the authoring docs say about the unbuilt docs graph', () => {
+  it('marks exactly the fields topic loading rejects as not read yet', () => {
+    const notReadYet = graphFieldsDoc.fields
+      .filter(field => /Not read yet/.test(field.description))
+      .map(field => field.name);
+    expect(notReadYet.sort()).toEqual([...GRAPH_ONLY_FIELDS].sort());
+    for (const field of graphFieldsDoc.fields) {
+      if (notReadYet.includes(field.name)) {
+        expect(field.description).toMatch(/fails to load/);
+      }
+    }
+    expect(graphFieldsDoc.description).toMatch(/not built yet/);
+  });
+
+  it('says a topic using a graph block fails to load', () => {
+    const content = referenceDoc.fields
+      .flatMap(field => [field, ...(field.fields ?? [])])
+      .find(field => field.name === 'sections[].content');
+    for (const type of GRAPH_BLOCK_TYPES) {
+      expect(content.description).toContain(type);
+    }
+    expect(content.description).toMatch(/fails to load/);
+  });
+
+  it('says namespace docs are not loaded yet', () => {
+    expect(namespaceDoc.description).toMatch(/Not loaded yet/);
+    expect(
+      problemsInTopic({
+        ...namespaceDoc.examples?.[0],
+        type: 'namespace',
+        name: 'x',
+      }),
+    ).toEqual([
+      '"x" is a namespace doc. Only the docs graph reads namespace docs, and it is not built yet; remove this file from the docs directory.',
+    ]);
+  });
 });
 
 describe('auditAuthoringSelfDocs', () => {
@@ -68,17 +119,25 @@ describe('auditAuthoringSelfDocs', () => {
       path.join(root, 'kept', 'forgotten.doc.mjs'),
       "export const doc = {name: 'forgotten', description: 'Not listed.'};\n",
     );
-    const audit = await auditAuthoringSelfDocs({root, sources: ['kept/kept.doc.mjs']});
+    const audit = await auditAuthoringSelfDocs({
+      root,
+      sources: ['kept/kept.doc.mjs'],
+    });
     expect(audit.unreachable).toEqual(['kept/forgotten.doc.mjs']);
   });
 
   it('reports a self-doc that fails to load instead of throwing', async () => {
-    fs.writeFileSync(path.join(root, 'kept', 'broken.doc.mjs'), 'export const doc = {;\n');
+    fs.writeFileSync(
+      path.join(root, 'kept', 'broken.doc.mjs'),
+      'export const doc = {;\n',
+    );
     const audit = await auditAuthoringSelfDocs({
       root,
       sources: ['kept/kept.doc.mjs', 'kept/broken.doc.mjs'],
     });
-    expect(audit.failed.map(entry => entry.source)).toEqual(['kept/broken.doc.mjs']);
+    expect(audit.failed.map(entry => entry.source)).toEqual([
+      'kept/broken.doc.mjs',
+    ]);
     expect(audit.sections).toBe(1);
   });
 

package/foundation/discovery/docs-discovery.d.mts

@@ -94,6 +94,10 @@ export { withSourceTitle };
  * unlike component discovery, whose built-ins belong to core.
  */
 export const BUILTIN_DOCS_PACKAGE: import("../../authoring/index.js").ProviderId;
+/** Blocks that are valid authoring but require the compiled graph renderer. */
+export const GRAPH_BLOCK_TYPES: Set<string>;
+/** Doc fields only the docs graph reads; a topic that sets one fails to load. */
+export const GRAPH_ONLY_FIELDS: string[];
 /**
  * Every topic a project can read, and the relationships between them.
  *