@json-to-office/shared 2.6.0 → 3.0.0

package/dist/{chunk-6TNT7DGC.js → chunk-LFHU4EOV.js}

@@ -59,6 +59,7 @@ function restructureNameDiscriminatedUnions(schema) {
       obj.required = ["name"];
       obj.properties = {
         name: {
+          description: "Component or registered plugin to render.",
           anyOf: [...groups.entries()].map(
             ([name, group]) => nameEntry(name, group)
           )
@@ -168,7 +169,8 @@ function convertToJsonSchema(schema, options = {}) {
     $id,
     title,
     description,
-    definitions = {}
+    definitions = {},
+    enrich
   } = options;
   const schemaJson = JSON.parse(JSON.stringify(schema));
   if (schemaJson.$id && typeof schemaJson.$id === "string" && /^T\d+$/.test(schemaJson.$id)) {
@@ -214,6 +216,7 @@ function convertToJsonSchema(schema, options = {}) {
     jsonSchema.definitions = extractedDefinitions;
   }
   fixSchemaReferences(jsonSchema);
+  enrich?.(jsonSchema);
   restructureNameDiscriminatedUnions(jsonSchema);
   return jsonSchema;
 }
@@ -294,4 +297,4 @@ export {
   exportSchemaToFile,
   createComponentSchemaObject
 };
-//# sourceMappingURL=chunk-6TNT7DGC.js.map
+//# sourceMappingURL=chunk-LFHU4EOV.js.map

package/dist/chunk-LFHU4EOV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schemas/schema-utils.ts","../src/schemas/discriminated-unions.ts"],"sourcesContent":["import { Type, TSchema } from '@sinclair/typebox';\nimport { restructureNameDiscriminatedUnions } from './discriminated-unions';\nimport type { ComponentDefinition } from '../types/components';\n\nexport interface ComponentSchemaConfig {\n  schema: TSchema;\n  title: string;\n  description: string;\n  requiresName?: boolean;\n  enhanceForRichContent?: boolean;\n}\n\nfunction replaceRefs(\n  obj: Record<string, unknown>,\n  target: string,\n  replacement: string\n): void {\n  if (typeof obj !== 'object' || obj === null) return;\n  if (Array.isArray(obj)) {\n    obj.forEach((item) => {\n      if (typeof item === 'object' && item !== null) {\n        replaceRefs(item as Record<string, unknown>, target, replacement);\n      }\n    });\n    return;\n  }\n  if (obj.$ref === target) {\n    obj.$ref = replacement;\n  }\n  for (const value of Object.values(obj)) {\n    if (typeof value === 'object' && value !== null) {\n      replaceRefs(value as Record<string, unknown>, target, replacement);\n    }\n  }\n}\n\n/**\n * Resolve the bare `$ref` values TypeBox leaves behind into JSON Pointers.\n *\n * `rootDefinitionName` is only the fallback for a reference that names nothing\n * hoisted. A schema may carry several recursive definitions — the DOCX\n * document schema carries one per renderer — so a bare reference that matches\n * an actual definition resolves to *that* one, which is what keeps the two\n * renderer views from collapsing into whichever was walked last.\n */\nexport function fixSchemaReferences(\n  schema: Record<string, unknown>,\n  rootDefinitionName = 'ComponentDefinition'\n): void {\n  const definitionNames = new Set(\n    Object.keys(\n      (schema.definitions as Record<string, unknown> | undefined) ?? {}\n    )\n  );\n  // Undefined when nothing by either name was hoisted. Substituting the root\n  // name regardless is how a reference to a definition that does not exist got\n  // written, and Ajv refuses to compile a schema containing one — so an\n  // unresolved reference is dropped rather than invented.\n  const definitionRef = (name: string): string | undefined => {\n    const target = definitionNames.has(name) ? name : rootDefinitionName;\n    return definitionNames.has(target) ? `#/definitions/${target}` : undefined;\n  };\n  const isBareDefinitionRef = (value: unknown): value is string =>\n    typeof value === 'string' &&\n    (/^T\\d+$/.test(value) ||\n      value === rootDefinitionName ||\n      definitionNames.has(value));\n\n  function traverse(obj: Record<string, unknown>, path = ''): void {\n    if (typeof obj !== 'object' || obj === null) return;\n\n    for (const [key, value] of Object.entries(obj)) {\n      const currentPath = path ? `${path}.${key}` : key;\n\n      if (value && typeof value === 'object') {\n        const schemaValue = value as Record<string, unknown>;\n\n        // Only when there is something to point at. A schema that holds\n        // components without embedding their definition (the theme schema\n        // holds `componentDefaults` but cannot carry a renderer's component\n        // union) keeps its untyped item: a `$ref` to a definition that was\n        // never hoisted is unresolvable, and Ajv refuses to compile the whole\n        // schema over it.\n        if (\n          schemaValue.type === 'array' &&\n          schemaValue.items &&\n          Object.keys(schemaValue.items).length === 0 &&\n          definitionNames.has(rootDefinitionName)\n        ) {\n          schemaValue.items = {\n            $ref: `#/definitions/${rootDefinitionName}`,\n          };\n        }\n\n        if (\n          schemaValue.type === 'array' &&\n          schemaValue.items &&\n          typeof schemaValue.items === 'object' &&\n          '$ref' in schemaValue.items &&\n          isBareDefinitionRef(\n            (schemaValue.items as Record<string, unknown>).$ref\n          )\n        ) {\n          const name = (schemaValue.items as Record<string, unknown>)\n            .$ref as string;\n          const ref = definitionRef(name);\n          // Untyped rather than dangling when the target was never hoisted.\n          schemaValue.items = ref ? { $ref: ref } : {};\n        }\n\n        if (isBareDefinitionRef(schemaValue.$ref)) {\n          const ref = definitionRef(schemaValue.$ref as string);\n          if (ref) schemaValue.$ref = ref;\n          else delete schemaValue.$ref;\n        }\n\n        if (\n          key === '$id' &&\n          isBareDefinitionRef(value) &&\n          currentPath !== `definitions.${value}.$id`\n        ) {\n          delete obj[key];\n          continue;\n        }\n\n        traverse(value as Record<string, unknown>, currentPath);\n      }\n    }\n  }\n\n  traverse(schema);\n}\n\nexport function convertToJsonSchema(\n  schema: TSchema,\n  options: {\n    $schema?: string;\n    $id?: string;\n    title?: string;\n    description?: string;\n    definitions?: Record<string, unknown>;\n    /**\n     * Format-specific enrichment applied once references resolve and before\n     * the name-discriminated unions are restructured — the point at which a\n     * component union is still a flat `anyOf` a derivation can filter and\n     * copy. The PPTX block-body authoring schemas are added here.\n     */\n    enrich?: (schema: Record<string, unknown>) => void;\n  } = {}\n): Record<string, unknown> {\n  const {\n    $schema = 'http://json-schema.org/draft-07/schema#',\n    $id,\n    title,\n    description,\n    definitions = {},\n    enrich,\n  } = options;\n\n  const schemaJson = JSON.parse(JSON.stringify(schema));\n\n  if (\n    schemaJson.$id &&\n    typeof schemaJson.$id === 'string' &&\n    /^T\\d+$/.test(schemaJson.$id)\n  ) {\n    const recursiveId = schemaJson.$id;\n    delete schemaJson.$id;\n    replaceRefs(schemaJson, recursiveId, '#');\n  }\n\n  const extractedDefinitions: Record<string, unknown> = { ...definitions };\n\n  function extractRecursiveSchemas(\n    obj: Record<string, unknown>,\n    path = ''\n  ): void {\n    if (typeof obj !== 'object' || obj === null) return;\n\n    for (const [key, value] of Object.entries(obj)) {\n      if (value && typeof value === 'object') {\n        const schemaValue = value as Record<string, unknown>;\n\n        if (schemaValue.$id && typeof schemaValue.$id === 'string') {\n          const definitionName = schemaValue.$id;\n\n          if (path !== `definitions.${definitionName}`) {\n            const { $id: _id, ...schemaWithoutId } = schemaValue; // eslint-disable-line @typescript-eslint/no-unused-vars\n            extractedDefinitions[definitionName] = schemaWithoutId;\n            obj[key] = { $ref: `#/definitions/${definitionName}` };\n            extractRecursiveSchemas(\n              schemaWithoutId,\n              `definitions.${definitionName}`\n            );\n            continue;\n          }\n        }\n\n        extractRecursiveSchemas(\n          value as Record<string, unknown>,\n          path ? `${path}.${key}` : key\n        );\n      }\n    }\n  }\n\n  extractRecursiveSchemas(schemaJson);\n\n  const jsonSchema: Record<string, unknown> = { $schema };\n\n  if ($id) jsonSchema.$id = $id;\n\n  Object.assign(jsonSchema, schemaJson);\n\n  jsonSchema.$schema = $schema;\n  if ($id) jsonSchema.$id = $id;\n  if (title !== undefined) jsonSchema.title = title;\n  if (description !== undefined) jsonSchema.description = description;\n\n  if (Object.keys(extractedDefinitions).length > 0) {\n    jsonSchema.definitions = extractedDefinitions;\n  }\n\n  fixSchemaReferences(jsonSchema);\n  enrich?.(jsonSchema);\n  restructureNameDiscriminatedUnions(jsonSchema);\n\n  return jsonSchema;\n}\n\nexport function createComponentSchema(\n  name: string,\n  config: ComponentSchemaConfig,\n  containerNames: string[],\n  componentDefinitionSchema?: TSchema,\n  // The definition the recursive children reference. Callers whose component\n  // union is renderer-specific pass that renderer's name so the embedded\n  // definition and the `$ref` pointing at it agree.\n  rootDefinitionName = 'ComponentDefinition'\n): Record<string, unknown> {\n  const componentStructure: Record<string, unknown> = {\n    $schema: 'http://json-schema.org/draft-07/schema#',\n    $id: `${name}.schema.json`,\n    title: config.title,\n    description: config.description,\n    type: 'object',\n    required: ['name', 'props'],\n    properties: {\n      name: {\n        type: 'string',\n        const: name,\n        description: `Component name identifier (must be \"${name}\")`,\n      },\n      id: {\n        type: 'string',\n        description: 'Optional unique identifier for the component',\n      },\n      props: JSON.parse(JSON.stringify(config.schema)),\n    },\n  };\n\n  if (containerNames.includes(name)) {\n    (componentStructure.properties as Record<string, unknown>).children = {\n      type: 'array',\n      description: 'Children within this container',\n      items: {\n        $ref: `#/definitions/${rootDefinitionName}`,\n      },\n    };\n\n    if (componentDefinitionSchema) {\n      componentStructure.definitions = {\n        [rootDefinitionName]: JSON.parse(\n          JSON.stringify(componentDefinitionSchema)\n        ),\n      };\n    }\n  }\n\n  fixSchemaReferences(componentStructure, rootDefinitionName);\n  componentStructure.additionalProperties = false;\n\n  return componentStructure;\n}\n\nexport async function exportSchemaToFile(\n  schema: Record<string, unknown>,\n  outputPath: string,\n  options: { prettyPrint?: boolean } = {}\n): Promise<void> {\n  const { prettyPrint = true } = options;\n  const jsonSchema = prettyPrint\n    ? JSON.stringify(schema, null, 2)\n    : JSON.stringify(schema);\n  const fs = await import('fs/promises');\n  await fs.writeFile(outputPath, jsonSchema, 'utf-8');\n}\n\n/**\n * Create a TypeBox schema object for any component definition.\n * Works for both docx and pptx components.\n */\nexport function createComponentSchemaObject(\n  component: ComponentDefinition,\n  recursiveRef?: TSchema\n): TSchema {\n  const schema: Record<string, TSchema> = {\n    name: Type.Literal(component.name),\n    id: Type.Optional(Type.String()),\n    enabled: Type.Optional(\n      Type.Boolean({\n        default: true,\n        description:\n          'When false, this component is filtered out and not rendered. Defaults to true.',\n      })\n    ),\n  };\n\n  if (component.special?.hasSchemaField) {\n    schema.$schema = Type.Optional(Type.String({ format: 'uri' }));\n  }\n\n  schema.props = component.propsSchema;\n\n  if (component.hasChildren && recursiveRef) {\n    schema.children = Type.Optional(Type.Array(recursiveRef));\n  }\n\n  return Type.Object(schema, { additionalProperties: false });\n}\n","/**\n * Canonical `if/then` restructuring for name-discriminated component unions.\n *\n * The generators export component unions as a flat `anyOf`. Schema-driven\n * editors (Monaco, VS Code — vscode-json-languageservice) resolve a partially\n * typed node against an `anyOf` by picking the single best-matching branch:\n * while typing `{ \"name\": | }`, every branch requiring `props` fails\n * validation, so its name const never reached autocomplete, and diagnostics\n * reported one arbitrary branch's complaints (\"Value must be \\\"heading\\\"\",\n * \"Missing property \\\"props\\\"\") instead of the real problem.\n *\n * This transform rewrites each such union — at JSON-Schema export time only,\n * the runtime TypeBox validators are untouched — into the standard\n * discriminated-union dispatch:\n *\n *   {\n *     type: \"object\",\n *     required: [\"name\"],\n *     properties: { name: { anyOf: [{ const, description }, …] } },\n *     allOf: [\n *       { if: { properties: { name: { const } }, required: [\"name\"] },\n *         then: <branch> },\n *       …\n *     ]\n *   }\n *\n * The accepted set of documents is exactly the same — `properties.name` is\n * the enum the branches already imply, and each `then` is the original\n * branch — but editors now behave deterministically:\n * - completing `name` offers every component, with its description\n * - an empty object reports only `Missing property \"name\"`\n * - a wrong name reports only `Value is not accepted. Valid values: …`\n * - a valid name activates exactly its branch for keys, props and errors\n *\n * Standard draft-07 keywords only, so ajv and every schema-aware editor\n * agree. Versioned plugin branches share a name; they stay grouped in a\n * small `anyOf` inside their `then`, containing best-match ambiguity to the\n * component's own versions.\n */\n\ninterface SchemaNode {\n  [key: string]: unknown;\n}\n\ninterface NameConstEntry {\n  const: string;\n  type: 'string';\n  description?: string;\n}\n\n/** A union branch shaped `{ properties: { name: { const: \"...\" } } }`. */\nfunction branchNameConst(branch: unknown): string | undefined {\n  if (typeof branch !== 'object' || branch === null || Array.isArray(branch))\n    return undefined;\n  const name = ((branch as SchemaNode).properties as SchemaNode | undefined)\n    ?.name as SchemaNode | undefined;\n  return typeof name?.const === 'string' ? name.const : undefined;\n}\n\n/** True when the branch also discriminates on a `version` const (plugins). */\nfunction isVersionedBranch(branch: SchemaNode): boolean {\n  const version = (branch.properties as SchemaNode | undefined)?.version as\n    | SchemaNode\n    | undefined;\n  return typeof version?.const === 'string';\n}\n\nfunction branchRequiresName(branch: SchemaNode): boolean {\n  return Array.isArray(branch.required) && branch.required.includes('name');\n}\n\n/** Group branches by their name const, preserving union order. */\nfunction groupByName(branches: SchemaNode[]): Map<string, SchemaNode[]> {\n  const groups = new Map<string, SchemaNode[]>();\n  for (const branch of branches) {\n    const name = branchNameConst(branch)!;\n    const group = groups.get(name);\n    if (group) group.push(branch);\n    else groups.set(name, [branch]);\n  }\n  return groups;\n}\n\nfunction nameEntry(name: string, group: SchemaNode[]): NameConstEntry {\n  // Versioned plugins repeat the same name across version branches; the\n  // un-versioned fallback carries the cleanest component description.\n  const source =\n    group.find(\n      (b) => !isVersionedBranch(b) && typeof b.description === 'string'\n    ) ?? group.find((b) => typeof b.description === 'string');\n  return {\n    const: name,\n    type: 'string',\n    ...(source ? { description: source.description as string } : {}),\n  };\n}\n\n/**\n * Walk a JSON Schema and restructure every `anyOf` union whose branches are\n * all name-discriminated objects into the `if/then` dispatch shape above.\n *\n * Mutates in place. Conservative by design — a union is only restructured\n * when the rewrite is provably equivalent:\n * - every branch is an object with a `name` const that lists `name` as\n *   required (unions containing `$ref` or free-form branches are left alone;\n *   a `$ref`'s target union is restructured where it is defined)\n * - the node declares no `properties`, `allOf`, `if`, `required`,\n *   `additionalProperties` or `type` of its own that the rewrite would have\n *   to merge with\n * - at least two distinct names; single-name unions (a versioned plugin's\n *   variants) validate and complete fine as a plain anyOf\n */\nexport function restructureNameDiscriminatedUnions(schema: unknown): void {\n  const visited = new WeakSet<object>();\n\n  function walk(node: unknown): void {\n    if (typeof node !== 'object' || node === null) return;\n    if (visited.has(node)) return;\n    visited.add(node);\n\n    if (Array.isArray(node)) {\n      node.forEach(walk);\n      return;\n    }\n\n    const obj = node as SchemaNode;\n    const anyOf = obj.anyOf;\n    const isCandidate =\n      Array.isArray(anyOf) &&\n      anyOf.length >= 2 &&\n      anyOf.every(\n        (b) => branchNameConst(b) !== undefined && branchRequiresName(b)\n      ) &&\n      obj.properties === undefined &&\n      obj.allOf === undefined &&\n      obj.if === undefined &&\n      obj.required === undefined &&\n      // A sibling `additionalProperties` evaluates against the node's own\n      // (absent) `properties`; declaring `name` here would change what it\n      // rejects, so such unions are left alone.\n      obj.additionalProperties === undefined &&\n      (obj.type === undefined || obj.type === 'object');\n    // Dispatch needs at least two distinct names. Same-name groups (a\n    // versioned plugin's variants) stay a plain anyOf — restructuring them\n    // would recurse forever on the group it just created.\n    const groups = isCandidate ? groupByName(anyOf as SchemaNode[]) : undefined;\n    if (groups && groups.size >= 2) {\n      obj.type = 'object';\n      obj.required = ['name'];\n      obj.properties = {\n        name: {\n          description: 'Component or registered plugin to render.',\n          anyOf: [...groups.entries()].map(([name, group]) =>\n            nameEntry(name, group)\n          ),\n        },\n      };\n      obj.allOf = [...groups.entries()].map(([name, group]) => ({\n        if: {\n          properties: { name: { const: name } },\n          required: ['name'],\n        },\n        then: group.length === 1 ? group[0] : { anyOf: group },\n      }));\n      delete obj.anyOf;\n    }\n\n    for (const value of Object.values(obj)) walk(value);\n  }\n\n  walk(schema);\n}\n\n/**\n * Iterate the component branches of an exported union, whichever shape it is\n * in — the flat `anyOf` the generators emit, or the `if/then` dispatch this\n * module rewrites it into. For consumers that post-process branch objects\n * (description enhancement, theme-name injection, …).\n */\nexport function unionBranches(schema: unknown): SchemaNode[] {\n  if (typeof schema !== 'object' || schema === null) return [];\n  const obj = schema as SchemaNode;\n  if (Array.isArray(obj.anyOf)) {\n    return obj.anyOf.filter(\n      (b): b is SchemaNode => typeof b === 'object' && b !== null\n    );\n  }\n  if (Array.isArray(obj.allOf)) {\n    return obj.allOf.flatMap((entry): SchemaNode[] => {\n      const then = (entry as SchemaNode | null)?.then;\n      if (typeof then !== 'object' || then === null) return [];\n      const inner = (then as SchemaNode).anyOf;\n      return Array.isArray(inner)\n        ? inner.filter(\n            (b): b is SchemaNode => typeof b === 'object' && b !== null\n          )\n        : [then as SchemaNode];\n    });\n  }\n  return [];\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -1,13 +1,14 @@
-export { C as ComponentDefinition, a as ComponentSchemaConfig, c as convertToJsonSchema, b as createComponentSchema, d as createComponentSchemaObject, e as exportSchemaToFile, f as fixSchemaReferences } from './schema-utils-C5Qdzsgy.js';
+export { C as ComponentDefinition, a as ComponentSchemaConfig, c as convertToJsonSchema, b as createComponentSchema, d as createComponentSchemaObject, e as exportSchemaToFile, f as fixSchemaReferences } from './schema-utils-B2i75lAT.js';
 export { AddWarningFunction, GenerationWarning } from './types/warnings.js';
 import { F as FontRegistryEntry, c as FontRuntimeOpts, R as ResolvedFontSource, b as ResolvedFont, a as RasterizeFontFace } from './types-kcQwhOlf.js';
 export { D as DEFAULT_VISUAL_DPI, d as FontFamilyNameSchema, e as FontRegistryDefinition, f as FontRegistryEntrySchema, g as FontRegistrySchema, h as FontSource, i as FontSourceSchema, H as HighchartsHeaders, j as HighchartsHeadersResolver, k as HighchartsServiceConfig, M as MAX_RASTERIZE_BATCH_SLIDES, l as MAX_RASTERIZE_FONTS, m as MAX_RASTERIZE_FONT_BYTES, n as MAX_VISUAL_DPI, o as MIN_VISUAL_DPI, P as PptxBatchRasterizer, p as PptxRasterizeBatchRequest, q as PptxRasterizeBatchResult, r as PptxRasterizeBatchSlide, s as PptxRasterizeBatchSlideResult, t as PptxRasterizeFailureStage, u as PptxRasterizeRequest, v as PptxRasterizeResult, w as PptxRasterizer, x as PptxServiceConfig, y as PptxServiceHeaders, z as PptxServiceHeadersResolver, S as SAFE_FONTS, A as SafeFontName, B as ServicesConfig, C as clampVisualDpi, E as isSafeFont } from './types-kcQwhOlf.js';
-export { F as FeatureRequirement, a as FeatureRequirementCollector, O as OfficeFormat, b as OfficeRenderer, R as RENDERER_DEPENDENCY_MISSING, c as RenderOptions, d as RendererDiagnostic, e as RendererDiagnosticSeverity, f as RendererRegistry, g as RendererStatus, h as UnsupportedRendererFeatureError, i as UnsupportedRendererFeatureErrorInit, j as assertNever, k as assertRendererSupports, l as diagnoseUnsupportedFeatures, p as partitionDiagnostics, r as rendererError, m as rendererWarning } from './capabilities-DtPF3aBj.js';
+import { O as OfficeFormat } from './capabilities-DtPF3aBj.js';
+export { F as FeatureRequirement, a as FeatureRequirementCollector, b as OfficeRenderer, R as RENDERER_DEPENDENCY_MISSING, c as RenderOptions, d as RendererDiagnostic, e as RendererDiagnosticSeverity, f as RendererRegistry, g as RendererStatus, h as UnsupportedRendererFeatureError, i as UnsupportedRendererFeatureErrorInit, j as assertNever, k as assertRendererSupports, l as diagnoseUnsupportedFeatures, p as partitionDiagnostics, r as rendererError, m as rendererWarning } from './capabilities-DtPF3aBj.js';
 export { DEFAULT_ERROR_CONFIG, ERROR_EMOJIS, ErrorFormatterConfig, calculatePosition, clearComponentNamesCache, createErrorConfig, createJsonParseError, extractStandardComponentNames, formatErrorMessage, formatErrorSummary, getLiteralValue, getObjectSchemaPropertyNames, getSchemaMetadata, groupErrorsByPath, isLiteralSchema, isObjectSchema, isUnionSchema, transformValueError, transformValueErrors } from './validation/unified/index.js';
 export { T as TransformedError, V as ValidationError, a as ValidationResult } from './types-BWFZ7OaO.js';
 export { ComponentValidationError, ComponentValidationResult, ComponentVersion, ComponentVersionMap, CustomComponent, DuplicateComponentError, PluginValidationOptions, PluginValidationResult, RenderContext, RenderFunction, UnknownPreservedComponentError, createComponent, createVersion, getValidationSummary, isValidationSuccess, resolveComponentVersion, validateCustomComponentProps } from './plugin/index.js';
 import * as _sinclair_typebox from '@sinclair/typebox';
-import { Static } from '@sinclair/typebox';
+import { Static, TSchema } from '@sinclair/typebox';
 export { ParsedSemver, compareSemver, isValidSemver, latestVersion, parseSemver } from './utils/semver.js';
 import '@sinclair/typebox/value';
 
@@ -1699,6 +1700,323 @@ declare function withChartFontFaceCss<T extends {
     };
 }>(props: T, faces: readonly RasterizeFontFace[], families: readonly string[]): T;
 
+/**
+ * Content roles a definition may assign to a slot. A quality profile reads
+ * them to require or measure content (an action title at most two lines, a
+ * source under every chart); the theme only styles them. No role adds a
+ * requirement on its own.
+ */
+declare const BLOCK_SLOT_ROLES: readonly ["actionTitle", "takeaway", "source", "tracker", "footer"];
+type BlockSlotRole = (typeof BLOCK_SLOT_ROLES)[number];
+interface BlockSlot {
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'component';
+    description?: string;
+    required?: boolean;
+    default?: unknown;
+    enum?: (string | number | boolean)[];
+    minItems?: number;
+    maxItems?: number;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    maxWords?: number;
+    oneLine?: boolean;
+    items?: BlockSlot;
+    properties?: Record<string, BlockSlot>;
+    role?: BlockSlotRole;
+}
+/** Definitions are authored data. No concrete block is registered by the core. */
+interface JsonBlockDefinition {
+    description?: string;
+    slots: Record<string, BlockSlot>;
+    body: unknown[];
+    /** DOCX section state, applied before rendering its header and footer. */
+    section?: {
+        tracker?: unknown;
+        header?: unknown[];
+        footer?: unknown[];
+        pageBreak?: boolean;
+        scope?: 'section' | 'following';
+    };
+    /** PPTX slide settings the invocation's slide inherits unless it states its own. */
+    slide?: {
+        background?: unknown;
+        grid?: unknown;
+        notes?: unknown;
+    };
+}
+declare const BlockSlotSchema: TSchema;
+declare const JsonBlockDefinitionSchema: _sinclair_typebox.TUnsafe<JsonBlockDefinition>;
+declare const BlockDefinitionsSchema: _sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnsafe<JsonBlockDefinition>>;
+declare const BlockInvocationPropsSchema: _sinclair_typebox.TObject<{
+    ref: _sinclair_typebox.TString;
+    slots: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnknown>>;
+}>;
+/** Portable JSON Schema for a single slot, also used by catalog/inspect clients. */
+declare function blockSlotJsonSchema(slot: BlockSlot): Record<string, unknown>;
+
+type Rec$1 = Record<string, unknown>;
+interface BlockIssue {
+    path: string;
+    code: string;
+    message: string;
+}
+declare class BlockEvaluationError extends Error {
+    readonly issues: BlockIssue[];
+    constructor(issues: BlockIssue[]);
+}
+declare const isBlockRecord: (v: unknown) => v is Rec$1;
+declare const blockPointerKey: (s: string) => string;
+declare function blockValueAt(root: unknown, path: string): unknown;
+declare function toAuthoredBlockPointer(map: Readonly<Record<string, string>>, pointer: string): string;
+/**
+ * Props a component placed in a slot may not carry: placement and group
+ * layout belong to the definition. Read by the runtime check below and by the
+ * editor schema that flags them inline.
+ */
+declare const BLOCK_SLOT_PLACEMENT_PROPS: readonly string[];
+declare const blockWordCount: (text: string) => number;
+/** Slot constraints and defaults are shared by validation and evaluation. */
+declare function resolveBlockSlot(slot: BlockSlot, input: unknown, path: string, issues: BlockIssue[]): unknown;
+declare function readBlockDefinitions(document: unknown): Record<string, JsonBlockDefinition>;
+declare function validateBlockDefinitions(definitions: unknown, format: 'docx' | 'pptx', reservedNames?: readonly string[]): BlockIssue[];
+declare function validateBlockInvocations(document: unknown, definitions: Record<string, JsonBlockDefinition>, format: 'docx' | 'pptx', reservedNames?: readonly string[]): BlockIssue[];
+interface BlockEnvironment {
+    slots: Rec$1;
+    slotSources?: Record<string, string>;
+    source: string;
+    definition: string;
+    context: Rec$1;
+    contextSources?: Record<string, string>;
+    item?: unknown;
+    itemSource?: string;
+}
+interface BlockSectionEffect {
+    settings: NonNullable<JsonBlockDefinition['section']>;
+    environment: BlockEnvironment;
+    path: string;
+}
+interface BlockSlideEffect {
+    settings: NonNullable<JsonBlockDefinition['slide']>;
+    environment: BlockEnvironment;
+    path: string;
+}
+interface BlockEvaluatorOptions {
+    format: 'docx' | 'pptx';
+    theme?: unknown;
+    context?: Rec$1;
+    contextSources?: Record<string, string>;
+    reservedNames?: readonly string[];
+    contextAt?: (path: string) => Rec$1;
+    measure?: (axis: 'width' | 'height', unit: 'pt' | 'twip' | 'in', context: Rec$1) => number;
+    onSection?: (effect: BlockSectionEffect) => void;
+    onSlide?: (effect: BlockSlideEffect) => void;
+}
+/** Pure bounded JSON composition. Plugins are expanded by the host, never evaluated here. */
+declare class JsonBlockEvaluator {
+    readonly definitions: Record<string, JsonBlockDefinition>;
+    readonly options: BlockEvaluatorOptions;
+    readonly sourceMap: Record<string, string>;
+    readonly blocks: string[];
+    private nodes;
+    constructor(definitions: Record<string, JsonBlockDefinition>, options: BlockEvaluatorOptions);
+    private guard;
+    evaluate(value: unknown, env: BlockEnvironment, out: string, definitionPath: string, depth?: number): unknown;
+    expand(value: unknown, path?: string, depth?: number): unknown;
+}
+
+declare function blockSlotsJsonSchema(definition: JsonBlockDefinition): Record<string, unknown>;
+/** Authored definitions and fill pointers for exactly this document revision. */
+declare function documentBlockMetadata(document: unknown): {
+    definitions: {
+        name: string;
+        definitionPointer: string;
+        definition: JsonBlockDefinition;
+        slotsSchema: Record<string, unknown>;
+    }[];
+    invocations: {
+        ref: string;
+        path: string;
+        slotsPath: string;
+        defined: boolean;
+    }[];
+    invalidDefinitions: boolean;
+};
+/** Compiled pointer → authored pointer. */
+type BlockSourceMap = Readonly<Record<string, string>>;
+/** A document with every block lowered in place, and how to get back. */
+interface ExpandedBlocks<T> {
+    document: T;
+    sourceMap: BlockSourceMap;
+    /** Authored pointers of every expanded invocation, in document order. */
+    blocks: readonly string[];
+}
+interface BlockSlotBudget {
+    block: string;
+    slot: string;
+    path: string;
+    words: number;
+    maxWords: number;
+}
+interface BlockSlotRoleValue {
+    block: string;
+    /** Authored pointer of the invocation. */
+    invocation: string;
+    slot: string;
+    role: BlockSlotRole;
+    /** Authored pointer of the slot value, whether or not one was supplied. */
+    path: string;
+    /** The resolved value after defaults; undefined when absent. */
+    value: unknown;
+}
+/** Metadata is always read from authored definitions, never from a named catalog. */
+declare function blockSlotBudgets(document: unknown, blocks: readonly string[]): BlockSlotBudget[];
+/**
+ * Every role-bearing slot of every invocation, present or not, so a profile
+ * can require one (a source under a chart) and measure another (an action
+ * title's length) at the authored pointer the author can patch.
+ */
+declare function blockSlotRoles(document: unknown, blocks: readonly string[]): BlockSlotRoleValue[];
+
+type Schema$1 = Record<string, any>;
+/**
+ * Derive authoring from the renderer/plugin schemas without weakening ordinary
+ * documents. Each value retains its literal schema and receives only directives
+ * whose result family can fit. Defaults and conditional branches recurse into
+ * that same value schema; repetition templates use the actual array item schema.
+ *
+ * Dispatch uses standard draft-07 conditionals, not overlapping anyOf branches:
+ * existing literal keys keep literal completion, and a directive selects only
+ * its own options. Empty/incomplete objects offer literal keys and directive
+ * starters. Memoized references keep recursive schemas finite and avoid copying
+ * the component graph into every default/then/else branch.
+ */
+declare function createBlockAuthoringSchema(definitions: Record<string, Schema$1>, componentDefinition: string, excludedComponents?: readonly string[], format?: OfficeFormat): Schema$1;
+
+type Rec = Record<string, unknown>;
+interface BlockCompositionOptions {
+    /** Registered code component names. JSON never loads or installs them. */
+    plugins: ReadonlySet<string>;
+    /** Expand one registered component at its authored path into standard output. */
+    render: (component: Rec, path: string) => Promise<unknown[]>;
+    /** Plugin names kept unexpanded in the `preserved` tree (schema export, inspection). */
+    preserve?: ReadonlySet<string>;
+}
+interface BlockComposition {
+    /** Every block and plugin lowered to standard components. */
+    standard: unknown;
+    /** The same tree with preserved plugins left as authored. */
+    preserved: unknown;
+}
+/**
+ * One bounded expansion for document-local JSON and registered code, in both
+ * directions: a plugin can emit a block, a block body or component slot can
+ * name a plugin, and either can nest. Provenance survives each boundary
+ * through the evaluator's source map; emitted output is wrapped in a `group`
+ * whose pointer maps back to the plugin's authored node.
+ *
+ * Format-neutral: the host supplies the evaluator (its format, theme and
+ * context) and validates the finished tree.
+ */
+declare function composeBlocksWithPlugins(evaluator: JsonBlockEvaluator, document: unknown, options: BlockCompositionOptions): Promise<BlockComposition>;
+
+type Schema = Record<string, any>;
+/** A block invocation as authored: the component the editor inserts. */
+interface BlockInvocationExample {
+    name: 'block';
+    props: {
+        ref: string;
+        slots?: Record<string, unknown>;
+    };
+}
+/**
+ * A slot's contract as short facts, in one order, for every place that shows
+ * it: the editor hover, the AI prompt, a catalog summary. "Required" means
+ * the caller must supply a value — a slot with a default never is.
+ */
+declare function blockSlotFacts(slot: BlockSlot): string[];
+/** The hover text for a slot: its description, then its contract in one line. */
+declare function blockSlotMarkdown(slot: BlockSlot): string;
+/**
+ * JSON Schema for one slot as the editor should see it. Unlike the portable
+ * `blockSlotJsonSchema`, a component slot references the real component
+ * definition — so a chart placed in it completes like any other chart — with
+ * the placement props the runtime rejects flagged at the key they appear on.
+ */
+declare function blockSlotEditorSchema(slot: BlockSlot, componentRef?: Schema): Schema;
+/** The `slots` object of an invocation of this definition. */
+declare function blockSlotsEditorSchema(definition: JsonBlockDefinition, componentRef?: Schema): Schema;
+/**
+ * The `props` of a `block` component given this document's definitions:
+ * `ref` enumerates the names with their descriptions, and each name
+ * dispatches `slots` to its own schema. With no definitions the reference
+ * stays a free string — the runtime says which name is missing.
+ */
+declare function blockInvocationPropsSchema(definitions: Record<string, JsonBlockDefinition>, componentRef?: Schema): Schema;
+/** Where the document-aware invocation props go in an exported schema. */
+interface DocumentBlockTarget {
+    /** A component definition under `definitions`, typically one per renderer. */
+    name: string;
+    /**
+     * What a component slot accepts — the content a slide or a section holds,
+     * as a reference into the same schema. Omitted, a component slot only asks
+     * for a `name`.
+     */
+    componentRef?: Schema;
+}
+/**
+ * Install the document-aware invocation props on every `block` branch inside
+ * the targeted component definitions — the definition's own branch and the
+ * copies a container inlines for its children — so an invocation completes
+ * the same wherever a slide or section places it. References out of the
+ * definition are not followed: block bodies live in their own derived
+ * definitions and keep their binding-aware props. Mutates in place; call on
+ * a copy of the shared schema.
+ */
+declare function applyDocumentBlocksToSchema(schema: Schema, definitions: Record<string, JsonBlockDefinition>, targets: readonly DocumentBlockTarget[]): void;
+/**
+ * The definitions a block needs beside itself, dependencies first, so a
+ * copied definition never leaves an unresolved reference behind. Unknown
+ * references and cycles are skipped: the runtime reports those.
+ */
+declare function blockDependencies(definitions: Record<string, JsonBlockDefinition>, name: string): string[];
+/**
+ * A valid invocation to insert: the first one the source document makes, if
+ * it makes one — real content, at the cardinality its author chose — else
+ * one synthesized from the slots at typical cardinality.
+ */
+declare function blockInvocationExample(name: string, definition: JsonBlockDefinition, options: {
+    document?: unknown;
+    format: OfficeFormat;
+}): BlockInvocationExample;
+/** An authoring reference extracted from a complete document. */
+interface BlockReference {
+    name: string;
+    format: OfficeFormat;
+    /** The document the definition comes from. */
+    template: string;
+    definitionPointer: string;
+    description: string;
+    definition: JsonBlockDefinition;
+    /** Portable slot schema, as `jto://blocks` publishes it. */
+    slotsSchema: Record<string, unknown>;
+    /** A valid invocation at typical cardinality. */
+    example: BlockInvocationExample;
+    /** Other definitions of the same document this one invokes, dependencies first. */
+    dependencies: string[];
+}
+/**
+ * Every block a complete document defines, as a reference an editor or an
+ * agent can copy: definition, dependencies and a working invocation. A
+ * document whose definitions do not validate contributes nothing — a
+ * reference must be copyable as is.
+ */
+declare function blockReferencesFromDocument(document: unknown, source: {
+    template: string;
+    format: OfficeFormat;
+}): BlockReference[];
+
 /**
  * Deep Merge Utilities
  * Generic deep-merge helpers used by both docx and pptx
@@ -1712,4 +2030,4 @@ declare function withChartFontFaceCss<T extends {
  */
 declare function mergeWithDefaults<T>(userConfig: T, themeDefaults: Partial<T>): T;
 
-export { CANVASES, type ChartTypography, ChromeSchema, DEFAULT_CHART_THEME_COLORS, type DesignCanvas, DesignSpacingSchema, type DesignSystem, DesignSystemProperties, DesignSystemSchema, FONT_URL_ALLOWLIST, type FontIssueCode, FontRegistry, FontRegistryEntry, type FontRegistryInput, type FontResolutionIssue, FontRuntimeOpts, type FontSubstitution, type FontValidationInput, type FontValidationResult, MotifSchema, POINTS_PER_PIXEL_96DPI, POPULAR_GOOGLE_FONTS, PaletteSchema, type PopularGoogleFont, ROLE_SCALE_STEPS, RasterizeFontFace, ResolvedFont, ResolvedFontSource, type SynthesizedFamily, TYPE_ROLES, TextCaseSchema, type TypeRole, type TypeRoleName, TypeRoleNameSchema, TypeRoleSchema, TypeRolesSchema, TypographySchema, UPSTREAM_OVERRIDES, type UpstreamOverride, type UpstreamVariant, WEIGHT_LABELS, applyExportMode, applyFontSubstitution, buildDefaultSubstitutionMap, capsFormatting, chartFamilyResolver, chartFontFaceCss, chartPointsPerPixel, collectFontNamesFromDocx, collectFontNamesFromPptx, cssFontFamily, defaultSubstituteFor, designCanvas, designColors, detectFontFormat, documentFontRegistry, fetchGoogleFontSources, getUpstreamOverride, isAllowedFontUrl, mergeFontRegistries, mergeWithDefaults, resolveDesignColor, resolveTypeRoles, restructureNameDiscriminatedUnions, rewriteFontFamilyName, synthesizeFamilyName, themeFontRegistry, unionBranches, validateDesignColors, validateFontReferences, withChartFontFaceCss, withChartTypography };
+export { BLOCK_SLOT_PLACEMENT_PROPS, BLOCK_SLOT_ROLES, type BlockComposition, type BlockCompositionOptions, BlockDefinitionsSchema, type BlockEnvironment, BlockEvaluationError, type BlockEvaluatorOptions, type BlockInvocationExample, BlockInvocationPropsSchema, type BlockIssue, type BlockReference, type BlockSectionEffect, type BlockSlideEffect, type BlockSlot, type BlockSlotBudget, type BlockSlotRole, type BlockSlotRoleValue, BlockSlotSchema, type BlockSourceMap, CANVASES, type ChartTypography, ChromeSchema, DEFAULT_CHART_THEME_COLORS, type DesignCanvas, DesignSpacingSchema, type DesignSystem, DesignSystemProperties, DesignSystemSchema, type DocumentBlockTarget, type ExpandedBlocks, FONT_URL_ALLOWLIST, type FontIssueCode, FontRegistry, FontRegistryEntry, type FontRegistryInput, type FontResolutionIssue, FontRuntimeOpts, type FontSubstitution, type FontValidationInput, type FontValidationResult, type JsonBlockDefinition, JsonBlockDefinitionSchema, JsonBlockEvaluator, MotifSchema, OfficeFormat, POINTS_PER_PIXEL_96DPI, POPULAR_GOOGLE_FONTS, PaletteSchema, type PopularGoogleFont, ROLE_SCALE_STEPS, RasterizeFontFace, ResolvedFont, ResolvedFontSource, type SynthesizedFamily, TYPE_ROLES, TextCaseSchema, type TypeRole, type TypeRoleName, TypeRoleNameSchema, TypeRoleSchema, TypeRolesSchema, TypographySchema, UPSTREAM_OVERRIDES, type UpstreamOverride, type UpstreamVariant, WEIGHT_LABELS, applyDocumentBlocksToSchema, applyExportMode, applyFontSubstitution, blockDependencies, blockInvocationExample, blockInvocationPropsSchema, blockPointerKey, blockReferencesFromDocument, blockSlotBudgets, blockSlotEditorSchema, blockSlotFacts, blockSlotJsonSchema, blockSlotMarkdown, blockSlotRoles, blockSlotsEditorSchema, blockSlotsJsonSchema, blockValueAt, blockWordCount, buildDefaultSubstitutionMap, capsFormatting, chartFamilyResolver, chartFontFaceCss, chartPointsPerPixel, collectFontNamesFromDocx, collectFontNamesFromPptx, composeBlocksWithPlugins, createBlockAuthoringSchema, cssFontFamily, defaultSubstituteFor, designCanvas, designColors, detectFontFormat, documentBlockMetadata, documentFontRegistry, fetchGoogleFontSources, getUpstreamOverride, isAllowedFontUrl, isBlockRecord, mergeFontRegistries, mergeWithDefaults, readBlockDefinitions, resolveBlockSlot, resolveDesignColor, resolveTypeRoles, restructureNameDiscriminatedUnions, rewriteFontFamilyName, synthesizeFamilyName, themeFontRegistry, toAuthoredBlockPointer, unionBranches, validateBlockDefinitions, validateBlockInvocations, validateDesignColors, validateFontReferences, withChartFontFaceCss, withChartTypography };