@json-to-office/shared 2.6.0 → 3.0.0

package/dist/index.js

@@ -38,6 +38,18 @@ import {
   transformValueError,
   transformValueErrors
 } from "./chunk-LLBCT7WL.js";
+import {
+  FeatureRequirementCollector,
+  RENDERER_DEPENDENCY_MISSING,
+  RendererRegistry,
+  UnsupportedRendererFeatureError,
+  assertNever,
+  assertRendererSupports,
+  diagnoseUnsupportedFeatures,
+  partitionDiagnostics,
+  rendererError,
+  rendererWarning
+} from "./chunk-QLZNOXT5.js";
 import {
   convertToJsonSchema,
   createComponentSchema,
@@ -46,7 +58,7 @@ import {
   fixSchemaReferences,
   restructureNameDiscriminatedUnions,
   unionBranches
-} from "./chunk-6TNT7DGC.js";
+} from "./chunk-LFHU4EOV.js";
 import {
   CANVASES,
   ChromeSchema,
@@ -75,18 +87,6 @@ import {
   resolveTypeRoles,
   validateDesignColors
 } from "./chunk-4MJFAJFW.js";
-import {
-  FeatureRequirementCollector,
-  RENDERER_DEPENDENCY_MISSING,
-  RendererRegistry,
-  UnsupportedRendererFeatureError,
-  assertNever,
-  assertRendererSupports,
-  diagnoseUnsupportedFeatures,
-  partitionDiagnostics,
-  rendererError,
-  rendererWarning
-} from "./chunk-QLZNOXT5.js";
 import {
   compareSemver,
   isValidSemver,
@@ -1483,6 +1483,1850 @@ ${authored}` : css
   };
 }
 
+// src/blocks/schema.ts
+import { Type } from "@sinclair/typebox";
+var BLOCK_SLOT_ROLES = [
+  "actionTitle",
+  "takeaway",
+  "source",
+  "tracker",
+  "footer"
+];
+var BlockSlotSchema = Type.Recursive(
+  (Self) => Type.Object(
+    {
+      type: Type.Union(
+        [
+          "string",
+          "number",
+          "integer",
+          "boolean",
+          "object",
+          "array",
+          "component"
+        ].map((v) => Type.Literal(v)),
+        {
+          description: "Content type accepted by this slot. Use component for a document component or registered plugin."
+        }
+      ),
+      description: Type.Optional(
+        Type.String({
+          description: "Explain this slot\u2019s content and purpose to authors."
+        })
+      ),
+      required: Type.Optional(
+        Type.Boolean({
+          description: "Require a value when no default is provided. Defaults to false."
+        })
+      ),
+      default: Type.Optional(
+        Type.Unknown({
+          description: "Value used when the caller omits this slot. Must satisfy the slot\u2019s type and constraints."
+        })
+      ),
+      enum: Type.Optional(
+        Type.Array(
+          Type.Union([Type.String(), Type.Number(), Type.Boolean()]),
+          {
+            minItems: 1,
+            description: "Allowed scalar values for this slot."
+          }
+        )
+      ),
+      minItems: Type.Optional(
+        Type.Integer({
+          minimum: 0,
+          description: "Minimum number of array entries, inclusive."
+        })
+      ),
+      maxItems: Type.Optional(
+        Type.Integer({
+          minimum: 0,
+          description: "Maximum number of array entries, inclusive."
+        })
+      ),
+      minLength: Type.Optional(
+        Type.Integer({
+          minimum: 0,
+          description: "Minimum string length in characters, inclusive."
+        })
+      ),
+      maxLength: Type.Optional(
+        Type.Integer({
+          minimum: 0,
+          description: "Maximum string length in characters, inclusive."
+        })
+      ),
+      minimum: Type.Optional(
+        Type.Number({ description: "Minimum numeric value, inclusive." })
+      ),
+      maximum: Type.Optional(
+        Type.Number({ description: "Maximum numeric value, inclusive." })
+      ),
+      maxWords: Type.Optional(
+        Type.Integer({
+          minimum: 1,
+          description: "Maximum whitespace-separated word count. Exceeding it fails validation."
+        })
+      ),
+      oneLine: Type.Optional(
+        Type.Boolean({
+          description: "Reject newline characters in string values. Does not prevent visual line wrapping."
+        })
+      ),
+      items: Type.Optional({
+        ...Self,
+        description: "Slot type and constraints for each array entry."
+      }),
+      properties: Type.Optional(
+        Type.Record(Type.String(), Self, {
+          description: "Named child slots accepted by an object slot. Undeclared properties are rejected."
+        })
+      ),
+      role: Type.Optional(
+        Type.Union(
+          BLOCK_SLOT_ROLES.map((role) => Type.Literal(role)),
+          {
+            description: "Content role for quality profiles: actionTitle, takeaway, source, tracker or footer. A profile may require or measure it; the theme only styles it."
+          }
+        )
+      )
+    },
+    { additionalProperties: false }
+  ),
+  // Named so the export hoists it under a stable definition rather than a
+  // TypeBox ordinal that shifts with what the process built before it.
+  { $id: "BlockSlot" }
+);
+var JsonBlockDefinitionSchema = Type.Unsafe(
+  Type.Object(
+    {
+      description: Type.Optional(
+        Type.String({
+          description: "Describe what this reusable block renders and when to use it."
+        })
+      ),
+      slots: Type.Record(Type.String(), BlockSlotSchema, {
+        description: "Named inputs and their types, defaults and constraints. Use an empty object for a block with no inputs."
+      }),
+      body: Type.Array(Type.Unknown(), {
+        description: "Components and binding directives expanded in order when this block is invoked."
+      }),
+      section: Type.Optional(
+        Type.Object(
+          {
+            tracker: Type.Optional(
+              Type.Unknown({
+                description: "Section tracker value or binding, available to headers and footers through $context at /section/tracker."
+              })
+            ),
+            header: Type.Optional(
+              Type.Array(Type.Unknown(), {
+                description: "Header component templates. Explicit header settings on the section take precedence."
+              })
+            ),
+            footer: Type.Optional(
+              Type.Array(Type.Unknown(), {
+                description: "Footer component templates. Explicit footer settings on the section take precedence."
+              })
+            ),
+            pageBreak: Type.Optional(
+              Type.Boolean({
+                description: "Start the containing section on a new page. An explicit section pageBreak setting takes precedence."
+              })
+            ),
+            scope: Type.Optional(
+              Type.Union([Type.Literal("section"), Type.Literal("following")], {
+                description: "Apply header/footer templates to this section only, or inherit them in following sections. Defaults to section."
+              })
+            )
+          },
+          {
+            additionalProperties: false,
+            description: "DOCX section tracker, header/footer templates and page-break behavior. Place this block at the section boundary."
+          }
+        )
+      ),
+      slide: Type.Optional(
+        Type.Object(
+          {
+            background: Type.Optional(
+              Type.Unknown({
+                description: "Slide background (color, gradient or image) or a binding. A background the slide states itself takes precedence."
+              })
+            ),
+            grid: Type.Optional(
+              Type.Unknown({
+                description: "Grid configuration merged over the presentation grid when resolving grid placements in this block\u2019s body."
+              })
+            ),
+            notes: Type.Optional(
+              Type.Unknown({
+                description: "Speaker notes or a binding. Notes the slide states itself take precedence."
+              })
+            )
+          },
+          {
+            additionalProperties: false,
+            description: "PPTX slide background, grid and notes supplied by this block. Invoke the block as a direct child of a slide."
+          }
+        )
+      )
+    },
+    { additionalProperties: false }
+  )
+);
+var BlockDefinitionsSchema = Type.Record(
+  Type.String({ pattern: "^[a-zA-Z][a-zA-Z0-9_-]*$" }),
+  JsonBlockDefinitionSchema,
+  {
+    description: "Document-local JSON block definitions. Names are not built into the engine."
+  }
+);
+var BlockInvocationPropsSchema = Type.Object(
+  {
+    ref: Type.String({
+      minLength: 1,
+      description: "Name in this document\u2019s props.blocks."
+    }),
+    slots: Type.Optional(
+      Type.Record(Type.String(), Type.Unknown(), {
+        description: "Input values keyed by the slot names declared in the referenced block definition."
+      })
+    )
+  },
+  { additionalProperties: false }
+);
+function blockSlotJsonSchema(slot) {
+  const { oneLine, properties, items, role: _role, ...rest } = slot;
+  delete rest.required;
+  delete rest.maxWords;
+  if (slot.type === "component") {
+    return {
+      type: "object",
+      properties: { name: { type: "string" } },
+      required: ["name"],
+      description: slot.description
+    };
+  }
+  return {
+    ...rest,
+    ...oneLine && { pattern: "^[^\\r\\n]*$" },
+    ...items && { items: blockSlotJsonSchema(items) },
+    ...properties && {
+      properties: Object.fromEntries(
+        Object.entries(properties).map(([key, value]) => [
+          key,
+          blockSlotJsonSchema(value)
+        ])
+      ),
+      required: Object.entries(properties).filter(([, value]) => value.required && value.default === void 0).map(([key]) => key),
+      additionalProperties: false
+    }
+  };
+}
+
+// src/blocks/directives.ts
+var BLOCK_DIRECTIVES = {
+  $slot: { keys: ["$slot", "default", "props"], result: "dynamic" },
+  $item: { keys: ["$item", "default", "props"], result: "dynamic" },
+  $theme: { keys: ["$theme", "default"], result: "dynamic" },
+  $context: { keys: ["$context", "default"], result: "dynamic" },
+  $count: { keys: ["$count"], result: "number" },
+  $if: { keys: ["$if", "then", "else"], result: "dynamic" },
+  $each: { keys: ["$each", "template"], result: "array" },
+  $join: { keys: ["$join", "separator", "keepEmpty"], result: "string" },
+  $measure: { keys: ["$measure", "fraction", "unit"], result: "number" }
+};
+
+// src/blocks/evaluator.ts
+import { Value } from "@sinclair/typebox/value";
+var BlockEvaluationError = class extends Error {
+  constructor(issues) {
+    super(issues.map((i) => `${i.path}: ${i.message}`).join("\n"));
+    this.issues = issues;
+    this.name = "BlockEvaluationError";
+  }
+};
+var isBlockRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var blockPointerKey = (s) => s.replace(/~/g, "~0").replace(/\//g, "~1");
+var own = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+function blockValueAt(root, path) {
+  if (path === "") return root;
+  if (!path.startsWith("/")) return void 0;
+  let value = root;
+  for (const part of path.slice(1).split("/")) {
+    const key = part.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (!isBlockRecord(value) && !Array.isArray(value) || !own(value, key))
+      return void 0;
+    value = value[key];
+  }
+  return value;
+}
+function toAuthoredBlockPointer(map, pointer2) {
+  let best;
+  for (const path of Object.keys(map)) {
+    if ((pointer2 === path || pointer2.startsWith(`${path}/`)) && (best === void 0 || path.length > best.length))
+      best = path;
+  }
+  return best === void 0 ? pointer2 : `${map[best]}${pointer2.slice(best.length)}`;
+}
+var BLOCK_SLOT_PLACEMENT_PROPS = [
+  "x",
+  "y",
+  "w",
+  "h",
+  "position",
+  "grid",
+  "gridConfig",
+  "direction",
+  "gap",
+  "weights",
+  "alignment",
+  "spacing"
+];
+var blockWordCount = (text) => text.trim() === "" ? 0 : text.trim().split(/\s+/).length;
+var present = (value) => value !== void 0 && value !== null && value !== "" && value !== false && (!Array.isArray(value) || value.length > 0);
+var fail = (path, code, message) => {
+  throw new BlockEvaluationError([{ path, code, message }]);
+};
+function resolveBlockSlot(slot, input, path, issues) {
+  const value = input === void 0 && slot.default !== void 0 ? structuredClone(slot.default) : input;
+  if (value === void 0) {
+    if (slot.required)
+      issues.push({
+        path,
+        code: "block_required_slot",
+        message: "Required block slot is missing."
+      });
+    return void 0;
+  }
+  const validType = slot.type === "array" ? Array.isArray(value) : slot.type === "component" ? isBlockRecord(value) && typeof value.name === "string" : slot.type === "object" ? isBlockRecord(value) : slot.type === "integer" ? typeof value === "number" && Number.isInteger(value) : typeof value === slot.type && (typeof value !== "number" || Number.isFinite(value));
+  if (!validType) {
+    issues.push({
+      path,
+      code: "block_slot_type",
+      message: `Expected ${slot.type}.`
+    });
+    return value;
+  }
+  const issue = (message) => issues.push({ path, code: "block_slot_budget", message });
+  if (slot.enum && !slot.enum.includes(value))
+    issue("Value is not one of the declared choices.");
+  if (typeof value === "string") {
+    if (slot.oneLine && /[\r\n]/.test(value))
+      issue("Slot must contain one line.");
+    if (slot.minLength !== void 0 && value.length < slot.minLength)
+      issue(`Minimum length is ${slot.minLength}.`);
+    if (slot.maxLength !== void 0 && value.length > slot.maxLength)
+      issue(`Maximum length is ${slot.maxLength}.`);
+    if (slot.maxWords !== void 0 && blockWordCount(value) > slot.maxWords)
+      issue(`Maximum word count is ${slot.maxWords}.`);
+  }
+  if (typeof value === "number") {
+    if (slot.minimum !== void 0 && value < slot.minimum)
+      issue(`Minimum value is ${slot.minimum}.`);
+    if (slot.maximum !== void 0 && value > slot.maximum)
+      issue(`Maximum value is ${slot.maximum}.`);
+  }
+  if (Array.isArray(value)) {
+    if (slot.minItems !== void 0 && value.length < slot.minItems)
+      issue(`Minimum item count is ${slot.minItems}.`);
+    if (slot.maxItems !== void 0 && value.length > slot.maxItems)
+      issue(`Maximum item count is ${slot.maxItems}.`);
+    return slot.items ? value.map(
+      (v, i) => resolveBlockSlot(slot.items, v, `${path}/${i}`, issues)
+    ) : value;
+  }
+  if (slot.type === "component" && isBlockRecord(value)) {
+    const checkPlacement = (node, pointer2, depth = 0) => {
+      if (depth > 64) {
+        issues.push({
+          path: pointer2,
+          code: "block_expansion_limit",
+          message: "Component slot exceeds 64 levels."
+        });
+        return;
+      }
+      if (Array.isArray(node)) {
+        node.forEach(
+          (item, i) => checkPlacement(item, `${pointer2}/${i}`, depth + 1)
+        );
+        return;
+      }
+      if (!isBlockRecord(node)) return;
+      const props = typeof node.name === "string" && isBlockRecord(node.props) ? node.props : {};
+      for (const key of BLOCK_SLOT_PLACEMENT_PROPS) {
+        if (own(props, key))
+          issues.push({
+            path: `${pointer2}/props/${key}`,
+            code: "block_slot_placement",
+            message: "Block placement belongs in the definition, not in a component slot."
+          });
+      }
+      for (const [key, item] of Object.entries(node))
+        checkPlacement(item, `${pointer2}/${blockPointerKey(key)}`, depth + 1);
+    };
+    checkPlacement(value, path);
+  }
+  if (slot.type === "object" && isBlockRecord(value) && slot.properties)
+    return resolveBlockSlots(slot.properties, value, path, issues);
+  return value;
+}
+function resolveBlockSlots(slots, values, path, issues) {
+  const out = {};
+  for (const key of Object.keys(values)) {
+    if (!own(slots, key))
+      issues.push({
+        path: `${path}/${blockPointerKey(key)}`,
+        code: "block_unknown_slot",
+        message: `Unknown slot '${key}'. Expected: ${Object.keys(slots).join(", ")}.`
+      });
+  }
+  for (const [key, slot] of Object.entries(slots)) {
+    const value = resolveBlockSlot(
+      slot,
+      own(values, key) ? values[key] : void 0,
+      `${path}/${blockPointerKey(key)}`,
+      issues
+    );
+    if (value !== void 0)
+      Object.defineProperty(out, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true
+      });
+  }
+  return out;
+}
+var DIRECTIVES = Object.fromEntries(
+  Object.entries(BLOCK_DIRECTIVES).map(([key, directive]) => [
+    key,
+    directive.keys
+  ])
+);
+function slotDescriptorAt(slots, pointer2) {
+  let descriptor = { type: "object", properties: slots };
+  for (const escaped of pointer2.slice(1).split("/")) {
+    const key = escaped.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (descriptor?.type === "object") {
+      if (!descriptor.properties) return { type: "object" };
+      descriptor = own(descriptor.properties, key) ? descriptor.properties[key] : void 0;
+    } else if (descriptor?.type === "array" && /^(0|[1-9]\d*)$/.test(key))
+      descriptor = descriptor.items ?? { type: "object" };
+    else if (descriptor?.type === "component") return { type: "object" };
+    else return void 0;
+  }
+  return descriptor;
+}
+function checkTemplate(value, path, slots, issues, repeated = false, depth = 0) {
+  if (depth > 64) {
+    issues.push({
+      path,
+      code: "block_depth",
+      message: "Definition exceeds 64 levels."
+    });
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach(
+      (v, i) => checkTemplate(v, `${path}/${i}`, slots, issues, repeated, depth + 1)
+    );
+    return;
+  }
+  if (!isBlockRecord(value)) return;
+  const keys = Object.keys(value).filter((k) => k.startsWith("$"));
+  if (keys.length) {
+    const key = keys[0];
+    const allowed = DIRECTIVES[key];
+    if (!allowed || keys.length !== 1 || Object.keys(value).some((k) => !allowed.includes(k))) {
+      issues.push({
+        path,
+        code: "block_invalid_binding",
+        message: "Unknown or malformed block directive."
+      });
+      return;
+    }
+    if ([
+      "$slot",
+      "$item",
+      "$theme",
+      "$context",
+      "$if",
+      "$each",
+      "$count"
+    ].includes(key)) {
+      const pointer2 = value[key];
+      if (typeof pointer2 !== "string" || pointer2 !== "" && !pointer2.startsWith("/"))
+        issues.push({
+          path,
+          code: "block_invalid_binding",
+          message: "Bindings use JSON Pointers, e.g. /title."
+        });
+      else if (["$slot", "$if", "$each", "$count"].includes(key)) {
+        const descriptor = slotDescriptorAt(slots, pointer2);
+        if (!descriptor)
+          issues.push({
+            path,
+            code: "block_unknown_binding",
+            message: `No slot field '${pointer2}' is declared.`
+          });
+        else if (["$each", "$count"].includes(key) && descriptor.type !== "array")
+          issues.push({
+            path,
+            code: "block_invalid_binding",
+            message: `${key} requires an array slot.`
+          });
+      }
+      if (key === "$item" && !repeated)
+        issues.push({
+          path,
+          code: "block_invalid_binding",
+          message: "$item is only available inside $each."
+        });
+      if ((key === "$slot" || key === "$item") && own(value, "props") && !isBlockRecord(value.props))
+        issues.push({
+          path: `${path}/props`,
+          code: "block_invalid_binding",
+          message: "props must be an object of component props merged beneath a component-slot value."
+        });
+    }
+    if (key === "$join" && value.keepEmpty !== void 0 && typeof value.keepEmpty !== "boolean")
+      issues.push({
+        path,
+        code: "block_invalid_binding",
+        message: "keepEmpty must be boolean."
+      });
+    if (key === "$if" && !own(value, "then"))
+      issues.push({
+        path,
+        code: "block_invalid_binding",
+        message: "$if requires then."
+      });
+    if (key === "$each" && (!own(value, "template") || Array.isArray(value.template)))
+      issues.push({
+        path,
+        code: "block_invalid_binding",
+        message: "$each requires one template value; use a group for multiple flow children."
+      });
+    if (key === "$join" && (!Array.isArray(value.$join) || value.separator !== void 0 && typeof value.separator !== "string"))
+      issues.push({
+        path,
+        code: "block_invalid_binding",
+        message: "$join requires an array and an optional string separator."
+      });
+    if (key === "$measure" && (!["width", "height"].includes(String(value.$measure)) || !["pt", "twip", "in"].includes(String(value.unit ?? "pt")) || value.fraction !== void 0 && (typeof value.fraction !== "number" || value.fraction < 0 || value.fraction > 1)))
+      issues.push({
+        path,
+        code: "block_invalid_binding",
+        message: "$measure requires width/height, pt/twip/in and a fraction between 0 and 1."
+      });
+  }
+  for (const [key, item] of Object.entries(value)) {
+    if (key.startsWith("$") && key !== "$join") continue;
+    checkTemplate(
+      item,
+      `${path}/${blockPointerKey(key)}`,
+      slots,
+      issues,
+      repeated || own(value, "$each"),
+      depth + 1
+    );
+  }
+}
+function readBlockDefinitions(document) {
+  const value = isBlockRecord(document) && isBlockRecord(document.props) ? document.props.blocks : void 0;
+  return value ?? {};
+}
+function validateBlockDefinitions(definitions, format, reservedNames = []) {
+  if (!Value.Check(BlockDefinitionsSchema, definitions))
+    return [...Value.Errors(BlockDefinitionsSchema, definitions)].slice(0, 100).map((e) => ({
+      path: `/props/blocks${e.path}`,
+      code: "block_invalid_definition",
+      message: e.message
+    }));
+  const issues = [];
+  for (const [name, def] of Object.entries(definitions)) {
+    const path = `/props/blocks/${blockPointerKey(name)}`;
+    if (reservedNames.includes(name))
+      issues.push({
+        path,
+        code: "block_name_collision",
+        message: `Block '${name}' conflicts with a registered component.`
+      });
+    if (format !== "docx" && def.section)
+      issues.push({
+        path: `${path}/section`,
+        code: "block_format",
+        message: "Section effects are DOCX-only."
+      });
+    if (format !== "pptx" && def.slide)
+      issues.push({
+        path: `${path}/slide`,
+        code: "block_format",
+        message: "Slide effects are PPTX-only."
+      });
+    const checkSlot = (slot, pointer2) => {
+      if (slot.default !== void 0)
+        resolveBlockSlot(slot, slot.default, `${pointer2}/default`, issues);
+      for (const [minimum, maximum] of [
+        ["minItems", "maxItems"],
+        ["minLength", "maxLength"],
+        ["minimum", "maximum"]
+      ]) {
+        if (slot[minimum] !== void 0 && slot[maximum] !== void 0 && slot[minimum] > slot[maximum])
+          issues.push({
+            path: pointer2,
+            code: "block_invalid_definition",
+            message: `${minimum} exceeds ${maximum}.`
+          });
+      }
+      if (slot.items) checkSlot(slot.items, `${pointer2}/items`);
+      for (const [key, nested] of Object.entries(slot.properties ?? {}))
+        checkSlot(nested, `${pointer2}/properties/${blockPointerKey(key)}`);
+    };
+    for (const [key, slot] of Object.entries(def.slots))
+      checkSlot(slot, `${path}/slots/${blockPointerKey(key)}`);
+    checkTemplate(def.body, `${path}/body`, def.slots, issues);
+    if (def.section)
+      checkTemplate(def.section, `${path}/section`, def.slots, issues);
+    if (def.slide) checkTemplate(def.slide, `${path}/slide`, def.slots, issues);
+  }
+  return issues;
+}
+function validateBlockInvocations(document, definitions, format, reservedNames = []) {
+  const issues = validateBlockDefinitions(definitions, format, reservedNames);
+  if (issues.length) return issues;
+  const walk = (v, path) => {
+    if (Array.isArray(v)) {
+      v.forEach((item, i) => walk(item, `${path}/${i}`));
+      return;
+    }
+    if (!isBlockRecord(v) || v.enabled === false) return;
+    if (v.name === "block" && isBlockRecord(v.props) && typeof v.props.ref === "string") {
+      const def = own(definitions, v.props.ref) ? definitions[v.props.ref] : void 0;
+      if (!def)
+        issues.push({
+          path: `${path}/props/ref`,
+          code: "block_unknown_reference",
+          message: `Block '${v.props.ref}' is not defined in this document.`
+        });
+      else {
+        if (v.props.slots === void 0 || isBlockRecord(v.props.slots))
+          resolveBlockSlots(
+            def.slots,
+            v.props.slots ?? {},
+            `${path}/props/slots`,
+            issues
+          );
+        if (def.section && !/^\/children\/\d+\/children\/\d+$/.test(path))
+          issues.push({
+            path,
+            code: "invalid_placement",
+            message: "A block with section effects must be a direct child of a top-level section."
+          });
+        if (def.slide && !/^\/children\/\d+\/children\/\d+$/.test(path))
+          issues.push({
+            path,
+            code: "invalid_placement",
+            message: "A block with slide effects must be a direct child of a slide."
+          });
+      }
+    }
+    for (const [key, item] of Object.entries(v)) {
+      if (path === "/props" && key === "blocks") continue;
+      walk(item, `${path}/${blockPointerKey(key)}`);
+    }
+  };
+  walk(document, "");
+  return issues;
+}
+var JsonBlockEvaluator = class {
+  constructor(definitions, options) {
+    this.definitions = definitions;
+    this.options = options;
+    const issues = validateBlockDefinitions(
+      definitions,
+      options.format,
+      options.reservedNames
+    );
+    if (issues.length) throw new BlockEvaluationError(issues);
+  }
+  sourceMap = {};
+  blocks = [];
+  nodes = 0;
+  guard(path, depth) {
+    if (depth > 64 || ++this.nodes > 5e4)
+      fail(
+        path,
+        "block_expansion_limit",
+        "Block expansion exceeds the depth/node limit (64/50000)."
+      );
+  }
+  evaluate(value, env, out, definitionPath, depth = 0) {
+    this.guard(env.source, depth);
+    this.sourceMap[out] = env.source;
+    if (Array.isArray(value)) {
+      const result2 = [];
+      value.forEach((v, i) => {
+        const evaluated = this.evaluate(
+          v,
+          env,
+          `${out}/${result2.length}`,
+          `${definitionPath}/${i}`,
+          depth + 1
+        );
+        if (evaluated !== void 0) {
+          if (isBlockRecord(v) && ("$if" in v || "$each" in v) && Array.isArray(evaluated)) {
+            const base = `${out}/${result2.length}`;
+            const maps = Object.entries(this.sourceMap).filter(
+              ([key]) => key.startsWith(`${base}/`)
+            );
+            for (const [key] of maps) delete this.sourceMap[key];
+            for (const [key, source] of maps) {
+              const rest = key.slice(base.length + 1);
+              const [index, ...suffix] = rest.split("/");
+              this.sourceMap[`${out}/${result2.length + Number(index)}${suffix.length ? "/" + suffix.join("/") : ""}`] = source;
+            }
+            result2.push(...evaluated);
+          } else result2.push(evaluated);
+        }
+      });
+      return result2;
+    }
+    if (!isBlockRecord(value)) return value;
+    if ("$slot" in value || "$item" in value || "$theme" in value || "$context" in value) {
+      const key = ["$slot", "$item", "$theme", "$context"].find(
+        (k) => k in value
+      );
+      const pointer2 = value[key];
+      const root = key === "$slot" ? env.slots : key === "$item" ? env.item : key === "$theme" ? this.options.theme : env.context;
+      const found = blockValueAt(root, pointer2);
+      if (key === "$slot")
+        this.sourceMap[out] = env.slotSources ? toAuthoredBlockPointer(env.slotSources, pointer2) : `${env.source}/props/slots${pointer2}`;
+      if (key === "$item")
+        this.sourceMap[out] = `${env.itemSource ?? env.source}${pointer2}`;
+      if (key === "$context")
+        this.sourceMap[out] = toAuthoredBlockPointer(env.contextSources ?? {}, pointer2) === pointer2 ? env.source : toAuthoredBlockPointer(env.contextSources ?? {}, pointer2);
+      let result2 = found !== void 0 ? structuredClone(found) : void 0;
+      if (result2 === void 0 && own(value, "default"))
+        result2 = this.evaluate(
+          value.default,
+          env,
+          out,
+          `${definitionPath}/default`,
+          depth + 1
+        );
+      if (result2 === void 0 && key === "$theme")
+        return fail(
+          definitionPath,
+          "block_unknown_theme_binding",
+          `Theme value '${pointer2}' is missing; declare a fallback or use an existing token.`
+        );
+      if ((key === "$slot" || key === "$item") && own(value, "props") && isBlockRecord(result2) && typeof result2.name === "string") {
+        const origin = this.sourceMap[out];
+        const defaults = this.evaluate(
+          value.props,
+          env,
+          `${out}/props`,
+          `${definitionPath}/props`,
+          depth + 1
+        );
+        const authored = isBlockRecord(result2.props) ? result2.props : {};
+        for (const propKey of Object.keys(authored)) {
+          const pointerKey = `${out}/props/${blockPointerKey(propKey)}`;
+          for (const mapped of Object.keys(this.sourceMap))
+            if (mapped === pointerKey || mapped.startsWith(`${pointerKey}/`))
+              delete this.sourceMap[mapped];
+          this.sourceMap[pointerKey] = `${origin}/props/${blockPointerKey(propKey)}`;
+        }
+        result2 = {
+          ...result2,
+          props: {
+            ...isBlockRecord(defaults) ? defaults : {},
+            ...authored
+          }
+        };
+      }
+      return result2;
+    }
+    if ("$if" in value)
+      return this.evaluate(
+        present(blockValueAt(env.slots, value.$if)) ? value.then : value.else,
+        env,
+        out,
+        definitionPath,
+        depth + 1
+      );
+    if ("$count" in value) {
+      const list = blockValueAt(env.slots, value.$count);
+      if (!Array.isArray(list))
+        return fail(
+          `${env.source}/props/slots${value.$count}`,
+          "block_slot_type",
+          "$count requires an array slot."
+        );
+      return list.length;
+    }
+    if ("$each" in value) {
+      const list = blockValueAt(env.slots, value.$each);
+      if (!Array.isArray(list))
+        return fail(
+          `${env.source}/props/slots${value.$each}`,
+          "block_slot_type",
+          "$each requires an array slot."
+        );
+      const result2 = [];
+      list.forEach((item, i) => {
+        const pointer2 = `${out}/${result2.length}`;
+        const evaluated = this.evaluate(
+          value.template,
+          {
+            ...env,
+            item,
+            itemSource: env.slotSources ? toAuthoredBlockPointer(env.slotSources, `${value.$each}/${i}`) : `${env.source}/props/slots${value.$each}/${i}`
+          },
+          pointer2,
+          `${definitionPath}/template`,
+          depth + 1
+        );
+        if (evaluated !== void 0) result2.push(evaluated);
+        else
+          for (const key of Object.keys(this.sourceMap)) {
+            if (key === pointer2 || key.startsWith(`${pointer2}/`))
+              delete this.sourceMap[key];
+          }
+      });
+      return result2;
+    }
+    if ("$join" in value) {
+      const values = value.$join.map(
+        (v, i) => this.evaluate(
+          v,
+          env,
+          `${out}/${i}`,
+          `${definitionPath}/$join/${i}`,
+          depth + 1
+        )
+      );
+      const first = values.findIndex(present);
+      if (first >= 0) this.sourceMap[out] = this.sourceMap[`${out}/${first}`];
+      return (value.keepEmpty === true ? values : values.filter(present)).map((v) => String(v ?? "")).join(String(value.separator ?? ""));
+    }
+    if ("$measure" in value) {
+      if (!this.options.measure)
+        return fail(
+          definitionPath,
+          "block_unsupported_operation",
+          "This format does not support $measure."
+        );
+      return this.options.measure(
+        value.$measure,
+        value.unit ?? "pt",
+        env.context
+      ) * Number(value.fraction ?? 1);
+    }
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+      const evaluated = this.evaluate(
+        item,
+        env,
+        `${out}/${blockPointerKey(key)}`,
+        `${definitionPath}/${blockPointerKey(key)}`,
+        depth + 1
+      );
+      if (evaluated !== void 0)
+        Object.defineProperty(result, key, {
+          value: evaluated,
+          enumerable: true,
+          configurable: true,
+          writable: true
+        });
+    }
+    return result;
+  }
+  expand(value, path = "", depth = 0) {
+    this.guard(path, depth);
+    if (Array.isArray(value))
+      return value.map((v, i) => this.expand(v, `${path}/${i}`, depth + 1));
+    if (!isBlockRecord(value)) return value;
+    if (value.name === "block" && value.enabled !== false) {
+      if (!isBlockRecord(value.props) || typeof value.props.ref !== "string")
+        return fail(
+          path,
+          "block_invalid_invocation",
+          "A block requires props.ref and optional props.slots."
+        );
+      if (Object.keys(value.props).some(
+        (key) => !["ref", "slots"].includes(key)
+      ) || value.props.slots !== void 0 && !isBlockRecord(value.props.slots))
+        return fail(
+          path,
+          "block_invalid_invocation",
+          "Block props accept only ref and an object of slots."
+        );
+      const def = own(this.definitions, value.props.ref) ? this.definitions[value.props.ref] : void 0;
+      if (!def)
+        return fail(
+          `${path}/props/ref`,
+          "block_unknown_reference",
+          `Block '${value.props.ref}' is not defined in this document.`
+        );
+      const issues = [];
+      const source = toAuthoredBlockPointer(this.sourceMap, path);
+      const slotsPath = `${path}/props/slots`;
+      const slots = resolveBlockSlots(
+        def.slots,
+        value.props.slots ?? {},
+        slotsPath,
+        issues
+      );
+      if (issues.length)
+        throw new BlockEvaluationError(
+          issues.map((issue) => ({
+            ...issue,
+            path: toAuthoredBlockPointer(this.sourceMap, issue.path)
+          }))
+        );
+      const slotSources = Object.fromEntries([
+        ["", toAuthoredBlockPointer(this.sourceMap, slotsPath)],
+        ...Object.entries(this.sourceMap).filter(([key]) => key.startsWith(`${slotsPath}/`)).map(([key, origin]) => [key.slice(slotsPath.length), origin])
+      ]);
+      const env = {
+        slots,
+        slotSources,
+        source,
+        definition: `/props/blocks/${blockPointerKey(value.props.ref)}`,
+        context: this.options.contextAt?.(path) ?? this.options.context ?? {},
+        contextSources: this.options.contextSources
+      };
+      if (def.section)
+        this.options.onSection?.({
+          settings: def.section,
+          environment: env,
+          path
+        });
+      if (def.slide)
+        this.options.onSlide?.({ settings: def.slide, environment: env, path });
+      this.blocks.push(source);
+      const children = this.evaluate(
+        def.body,
+        env,
+        `${path}/children`,
+        `${env.definition}/body`,
+        depth + 1
+      );
+      return {
+        name: "group",
+        ...value.id !== void 0 && { id: value.id },
+        children: this.expand(children, `${path}/children`, depth + 1)
+      };
+    }
+    if (value.enabled === false) return { ...value };
+    const result = { ...value };
+    for (const [key, item] of Object.entries(value)) {
+      if (path === "/props" && key === "blocks") continue;
+      Object.defineProperty(result, key, {
+        value: this.expand(item, `${path}/${blockPointerKey(key)}`, depth + 1),
+        enumerable: true,
+        configurable: true,
+        writable: true
+      });
+    }
+    return result;
+  }
+};
+
+// src/blocks/metadata.ts
+import { Value as Value2 } from "@sinclair/typebox/value";
+function blockSlotsJsonSchema(definition) {
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties: Object.fromEntries(
+      Object.entries(definition.slots).map(([key, slot]) => [
+        key,
+        blockSlotJsonSchema(slot)
+      ])
+    ),
+    required: Object.entries(definition.slots).filter(([, slot]) => slot.required && slot.default === void 0).map(([key]) => key)
+  };
+}
+function documentBlockMetadata(document) {
+  const definitions = readBlockDefinitions(document);
+  if (!Value2.Check(BlockDefinitionsSchema, definitions))
+    return { definitions: [], invocations: [], invalidDefinitions: true };
+  const invocations2 = [];
+  const walk = (value, path) => {
+    if (Array.isArray(value)) {
+      value.forEach((item, i) => walk(item, `${path}/${i}`));
+      return;
+    }
+    if (!isBlockRecord(value)) return;
+    if (value.name === "block" && isBlockRecord(value.props) && typeof value.props.ref === "string")
+      invocations2.push({
+        ref: value.props.ref,
+        path,
+        slotsPath: `${path}/props/slots`,
+        defined: Object.prototype.hasOwnProperty.call(
+          definitions,
+          value.props.ref
+        )
+      });
+    for (const [key, item] of Object.entries(value)) {
+      if (path === "/props" && key === "blocks") continue;
+      walk(item, `${path}/${blockPointerKey(key)}`);
+    }
+  };
+  walk(document, "");
+  return {
+    definitions: Object.entries(definitions).map(([name, definition]) => ({
+      name,
+      definitionPointer: `/props/blocks/${blockPointerKey(name)}`,
+      definition,
+      slotsSchema: blockSlotsJsonSchema(definition)
+    })),
+    invocations: invocations2,
+    invalidDefinitions: false
+  };
+}
+function visitInvocationSlots(document, blocks, visit) {
+  const definitions = readBlockDefinitions(document);
+  for (const path of blocks) {
+    const node = blockValueAt(document, path);
+    if (!isBlockRecord(node) || !isBlockRecord(node.props) || typeof node.props.ref !== "string")
+      continue;
+    const ref = node.props.ref;
+    const definition = definitions[ref];
+    if (!definition) continue;
+    const walk = (slot, value, pointer2, name) => {
+      visit(ref, slot, value, pointer2, name);
+      if (isBlockRecord(value) && slot.properties) {
+        for (const [key, property] of Object.entries(slot.properties)) {
+          walk(
+            property,
+            blockValueAt(value, `/${blockPointerKey(key)}`),
+            `${pointer2}/${blockPointerKey(key)}`,
+            `${name}.${key}`
+          );
+        }
+      }
+      if (Array.isArray(value) && slot.items)
+        value.forEach(
+          (item, i) => walk(slot.items, item, `${pointer2}/${i}`, name)
+        );
+    };
+    for (const [name, slot] of Object.entries(definition.slots)) {
+      const authored = blockValueAt(
+        node.props.slots,
+        `/${blockPointerKey(name)}`
+      );
+      walk(
+        slot,
+        authored === void 0 && slot.default !== void 0 ? slot.default : authored,
+        `${path}/props/slots/${blockPointerKey(name)}`,
+        name
+      );
+    }
+  }
+}
+function blockSlotBudgets(document, blocks) {
+  const result = [];
+  visitInvocationSlots(document, blocks, (ref, slot, value, pointer2, name) => {
+    if (typeof value === "string" && slot.maxWords !== void 0)
+      result.push({
+        block: ref,
+        slot: name,
+        path: pointer2,
+        words: blockWordCount(value),
+        maxWords: slot.maxWords
+      });
+  });
+  return result;
+}
+function blockSlotRoles(document, blocks) {
+  const result = [];
+  visitInvocationSlots(document, blocks, (ref, slot, value, pointer2, name) => {
+    if (!slot.role) return;
+    result.push({
+      block: ref,
+      invocation: pointer2.replace(/\/props\/slots\/.*$/, ""),
+      slot: name,
+      role: slot.role,
+      path: pointer2,
+      value
+    });
+  });
+  return result;
+}
+
+// src/blocks/schema-types.ts
+var allTypes = [
+  "null",
+  "boolean",
+  "number",
+  "string",
+  "array",
+  "object"
+];
+var intersection = (a, b) => new Set([...a].filter((value) => b.has(value)));
+var union = (sets) => new Set(sets.flatMap((set) => [...set]));
+var typeOf = (value) => value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+function possibleValueTypes(schema, resolve, seen = /* @__PURE__ */ new Set()) {
+  if (schema === false) return /* @__PURE__ */ new Set();
+  if (schema === true || seen.has(schema)) return new Set(allTypes);
+  const negated = schema.not;
+  if (negated === true || negated && typeof negated === "object" && Object.keys(negated).length === 0)
+    return /* @__PURE__ */ new Set();
+  const next = new Set(seen).add(schema);
+  let types = new Set(allTypes);
+  if (schema.type) {
+    const declared = Array.isArray(schema.type) ? schema.type : [schema.type];
+    types = intersection(
+      types,
+      new Set(
+        allTypes.filter(
+          (type) => declared.includes(type) || type === "number" && declared.includes("integer")
+        )
+      )
+    );
+  }
+  if (Object.hasOwn(schema, "const"))
+    types = intersection(types, /* @__PURE__ */ new Set([typeOf(schema.const)]));
+  if (Array.isArray(schema.enum))
+    types = intersection(types, new Set(schema.enum.map(typeOf)));
+  if (typeof schema.$ref === "string") {
+    const target = resolve(schema.$ref);
+    if (target !== void 0)
+      types = intersection(types, possibleValueTypes(target, resolve, next));
+  }
+  for (const key of ["anyOf", "oneOf"]) {
+    if (Array.isArray(schema[key]))
+      types = intersection(
+        types,
+        union(
+          schema[key].map(
+            (branch) => possibleValueTypes(branch, resolve, next)
+          )
+        )
+      );
+  }
+  if (Array.isArray(schema.allOf))
+    for (const branch of schema.allOf)
+      types = intersection(types, possibleValueTypes(branch, resolve, next));
+  if (negated && typeof negated === "object" && negated.type && Object.keys(negated).every(
+    (key) => ["type", "description", "title", "$comment"].includes(key)
+  )) {
+    const excluded = (Array.isArray(negated.type) ? negated.type : [negated.type]).filter((type) => type !== "integer");
+    types = new Set([...types].filter((type) => !excluded.includes(type)));
+  }
+  return types;
+}
+function arrayItemSchema(schema, resolve, seen = /* @__PURE__ */ new Set()) {
+  if (schema === false) return false;
+  if (schema === true || seen.has(schema)) return {};
+  const next = new Set(seen).add(schema);
+  const constraints = [];
+  if (typeof schema.$ref === "string") {
+    const target = resolve(schema.$ref);
+    if (target !== void 0)
+      constraints.push(arrayItemSchema(target, resolve, next));
+  }
+  if (schema.items !== void 0)
+    constraints.push(
+      Array.isArray(schema.items) ? {
+        anyOf: [
+          ...schema.items,
+          ...schema.additionalItems === false ? [] : [schema.additionalItems ?? {}]
+        ]
+      } : schema.items
+    );
+  for (const key of ["anyOf", "oneOf"])
+    if (Array.isArray(schema[key])) {
+      constraints.push({
+        anyOf: schema[key].filter(
+          (branch) => possibleValueTypes(branch, resolve).has("array")
+        ).map(
+          (branch) => arrayItemSchema(branch, resolve, next)
+        )
+      });
+    }
+  if (Array.isArray(schema.allOf))
+    constraints.push(
+      ...schema.allOf.map(
+        (branch) => arrayItemSchema(branch, resolve, next)
+      )
+    );
+  return constraints.length === 0 ? {} : constraints.length === 1 ? constraints[0] : { allOf: constraints };
+}
+
+// src/blocks/authoring-schema.ts
+var object = (properties, required) => ({
+  type: "object",
+  properties,
+  required,
+  additionalProperties: false
+});
+var pointer = (description) => ({
+  type: "string",
+  pattern: "^(|/.*)$",
+  description
+});
+var referenceDescriptions = (format) => ({
+  $slot: "Read a named input slot by JSON Pointer, e.g. /title or /client/name.",
+  $item: "Read the current $each entry by JSON Pointer. Use an empty string for the whole entry or /title for a property.",
+  $theme: "Read the active theme by JSON Pointer, e.g. /colors/primary. A missing value requires a default.",
+  $context: format === "pptx" ? "Read deck or slide context by JSON Pointer, e.g. /document/title, /slide/width or /slide/index." : "Read document or section context by JSON Pointer, e.g. /document/title or /section/tracker."
+});
+var measureDescriptions = (format) => format === "pptx" ? {
+  axis: "Measure the slide canvas width or height, in the unit given.",
+  unit: "Measurement unit: points, twentieths of a point, or inches. Defaults to pt; use in for frame coordinates."
+} : {
+  axis: "Measure the usable page width or height after margins, using the containing section\u2019s page settings.",
+  unit: "Measurement unit: points, twentieths of a point, or inches. Defaults to pt."
+};
+var describe = (schema, description) => ({
+  ...typeof schema === "boolean" ? { allOf: [schema] } : schema,
+  description
+});
+var metadata = (schema) => typeof schema === "boolean" ? {} : {
+  ...schema.description && { description: schema.description },
+  ...schema.markdownDescription && {
+    markdownDescription: schema.markdownDescription
+  }
+};
+var hasKey = (key) => ({ type: "object", required: [key] });
+var directiveNames = Object.keys(BLOCK_DIRECTIVES);
+function createBlockAuthoringSchema(definitions, componentDefinition, excludedComponents = [], format = "docx") {
+  const prefix = `BlockTemplate_${componentDefinition}`;
+  const references = referenceDescriptions(format);
+  const measure = measureDescriptions(format);
+  const bodyName = `${prefix}_Body`;
+  const ref = (name) => ({ $ref: `#/definitions/${name}` });
+  if (definitions[bodyName]) return ref(bodyName);
+  const originals = { ...definitions };
+  const source = originals[componentDefinition];
+  originals[componentDefinition] = {
+    ...source,
+    anyOf: (source.anyOf ?? [source]).filter(
+      (branch) => !excludedComponents.includes(branch.properties?.name?.const)
+    )
+  };
+  const resolve = (pointer2) => {
+    if (!pointer2.startsWith("#/definitions/")) return void 0;
+    let node = originals;
+    for (const key of pointer2.slice("#/definitions/".length).split("/")) {
+      const decoded = key.replace(/~1/g, "/").replace(/~0/g, "~");
+      if (!node || typeof node !== "object" || !Object.hasOwn(node, decoded))
+        return void 0;
+      node = node[decoded];
+    }
+    return typeof node === "boolean" || node && typeof node === "object" ? node : void 0;
+  };
+  const values = /* @__PURE__ */ new Map();
+  const literals = /* @__PURE__ */ new Map();
+  let nextId = 0;
+  const componentRef = ref(componentDefinition);
+  const shared = /* @__PURE__ */ new Map();
+  const share = (schema) => {
+    const key = JSON.stringify(schema);
+    let name = shared.get(key);
+    if (!name) {
+      name = `${prefix}_Shared${nextId++}`;
+      shared.set(key, name);
+      definitions[name] = schema;
+    }
+    return ref(name);
+  };
+  const presence = Object.fromEntries(
+    directiveNames.map((key) => [key, share(hasKey(key))])
+  );
+  const anyDirective = share({ anyOf: Object.values(presence) });
+  const starterPrefixes = [
+    .../* @__PURE__ */ new Set([
+      "",
+      ...directiveNames.flatMap(
+        (key) => Array.from(
+          { length: key.length - 1 },
+          (_, index) => key.slice(0, index + 1)
+        )
+      )
+    ])
+  ];
+  const starterObject = share({
+    type: "object",
+    // An enum here would itself become a list of bogus property suggestions.
+    propertyNames: {
+      pattern: `^(?:${starterPrefixes.map((key) => key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})$`
+    }
+  });
+  function literal(schema) {
+    if (typeof schema === "boolean") return schema;
+    const key = JSON.stringify(schema);
+    const cached = literals.get(key);
+    if (cached) return { ...ref(cached), ...metadata(schema) };
+    const name = `${prefix}_Literal${nextId++}`;
+    literals.set(key, name);
+    definitions[name] = {};
+    const result = { ...schema };
+    if (typeof schema.$ref === "string") {
+      const target = resolve(schema.$ref);
+      if (target !== void 0) {
+        const transformed = literal(target);
+        if (typeof transformed === "object") result.$ref = transformed.$ref;
+        else {
+          delete result.$ref;
+          if (!transformed) result.not = {};
+        }
+      }
+    }
+    if (schema.properties)
+      result.properties = Object.fromEntries(
+        Object.entries(
+          schema.properties
+        ).map(([key2, value]) => [
+          key2,
+          // Literal discriminators retain canonical component/version dispatch
+          // and their individual choice descriptions.
+          ["name", "version"].includes(key2) && typeof value === "object" && typeof value.const === "string" ? value : author(value)
+        ])
+      );
+    if (schema.patternProperties)
+      result.patternProperties = Object.fromEntries(
+        Object.entries(
+          schema.patternProperties
+        ).map(([key2, value]) => [key2, author(value)])
+      );
+    if (schema.items !== void 0)
+      result.items = Array.isArray(schema.items) ? schema.items.map((item) => author(item, true)) : author(schema.items, true);
+    for (const key2 of ["additionalProperties", "additionalItems"])
+      if (typeof schema[key2] === "object")
+        result[key2] = author(schema[key2], key2 === "additionalItems");
+    for (const key2 of ["anyOf", "oneOf", "allOf"])
+      if (Array.isArray(schema[key2]))
+        result[key2] = schema[key2].map((branch) => {
+          const transformed = literal(branch);
+          return typeof branch === "object" && typeof branch.properties?.name?.const === "string" && typeof transformed === "object" && transformed.$ref ? definitions[transformed.$ref.slice("#/definitions/".length)] : transformed;
+        });
+    for (const key2 of ["then", "else"])
+      if (schema[key2] !== void 0) result[key2] = literal(schema[key2]);
+    definitions[name] = result;
+    return { ...ref(name), ...metadata(schema) };
+  }
+  function author(input, sequence = false) {
+    if (input === false) return false;
+    const annotations = metadata(input);
+    const schema = typeof input === "object" ? { ...input } : input;
+    if (typeof schema === "object") {
+      delete schema.description;
+      delete schema.markdownDescription;
+    }
+    const key = `${sequence ? "sequence" : "value"}:${JSON.stringify(schema)}`;
+    const cached = values.get(key);
+    if (cached) return { ...ref(cached), ...annotations };
+    const name = `${prefix}_Value${nextId++}`;
+    values.set(key, name);
+    definitions[name] = {};
+    const self = ref(name);
+    const types = possibleValueTypes(schema, resolve);
+    if (types.size === 0) {
+      definitions[name] = { allOf: [literal(schema)] };
+      return self;
+    }
+    const value = () => sequence ? author(schema) : self;
+    const branch = () => sequence ? { anyOf: [self, { type: "array", items: self }] } : self;
+    const item = () => sequence ? value() : author(arrayItemSchema(schema, resolve));
+    const specs = {};
+    for (const directive of directiveNames) {
+      const result = BLOCK_DIRECTIVES[directive].result;
+      if (result !== "dynamic" && !types.has(result) && !(sequence && result === "array"))
+        continue;
+      switch (directive) {
+        case "$slot":
+        case "$item":
+        case "$theme":
+        case "$context":
+          specs[directive] = object(
+            {
+              [directive]: pointer(references[directive]),
+              default: describe(
+                value(),
+                "Fallback value or binding used only when the referenced value is missing. Null, false and empty values do not trigger it."
+              ),
+              ...directive === "$slot" || directive === "$item" ? {
+                props: {
+                  type: "object",
+                  description: "Component props merged beneath a component-slot value. Put placement (x, y, w, h, grid) and styling defaults here; the slot content may override styling but never placement."
+                }
+              } : {}
+            },
+            [directive]
+          );
+          break;
+        case "$if":
+          specs[directive] = object(
+            {
+              $if: pointer(
+                "Test a slot by JSON Pointer, e.g. /subtitle. Missing, null, false, empty text and empty arrays select else; zero selects then."
+              ),
+              then: describe(
+                branch(),
+                "Value or components to emit when the slot tested by $if is present."
+              ),
+              else: describe(
+                branch(),
+                "Value or components to emit otherwise. Omit to produce no output."
+              )
+            },
+            ["$if", "then"]
+          );
+          break;
+        case "$each":
+          specs[directive] = object(
+            {
+              $each: pointer(
+                "Repeat template for each entry in an array slot, e.g. /items. Read the current entry with $item."
+              ),
+              template: describe(
+                item(),
+                "One template evaluated per array entry. Use $item for the current entry and a group for multiple components."
+              )
+            },
+            ["$each", "template"]
+          );
+          break;
+        case "$count":
+          specs[directive] = object(
+            {
+              $count: pointer(
+                "Return the number of entries in an array slot, e.g. /items."
+              )
+            },
+            ["$count"]
+          );
+          break;
+        case "$join":
+          specs[directive] = object(
+            {
+              $join: {
+                type: "array",
+                items: author({}),
+                description: "Evaluate these values or bindings and join them as text. Empty values are skipped unless keepEmpty is true."
+              },
+              separator: {
+                type: "string",
+                description: "Text inserted between joined values. Defaults to an empty string."
+              },
+              keepEmpty: {
+                type: "boolean",
+                description: "Keep missing, null, false, empty text and empty arrays in the join. Defaults to false."
+              }
+            },
+            ["$join"]
+          );
+          break;
+        case "$measure":
+          specs[directive] = object(
+            {
+              $measure: {
+                enum: ["width", "height"],
+                description: measure.axis
+              },
+              fraction: {
+                type: "number",
+                minimum: 0,
+                maximum: 1,
+                description: "Fraction of the measured dimension, from 0 to 1. Defaults to 1."
+              },
+              unit: {
+                enum: ["pt", "twip", "in"],
+                description: measure.unit
+              }
+            },
+            ["$measure"]
+          );
+          break;
+        default: {
+          const exhaustive = directive;
+          throw new Error(
+            `Missing authoring schema for directive ${exhaustive}`
+          );
+        }
+      }
+    }
+    definitions[name] = {
+      allOf: [
+        {
+          if: anyDirective,
+          then: {
+            allOf: directiveNames.map((directive) => ({
+              if: presence[directive],
+              then: specs[directive] ? share({
+                ...specs[directive],
+                properties: Object.fromEntries(
+                  Object.entries(specs[directive].properties).map(
+                    ([key2, property]) => [key2, share(property)]
+                  )
+                )
+              }) : false
+            }))
+          },
+          else: literal(schema)
+        },
+        {
+          // Keep starters while the first key is empty or a partial directive
+          // ("$", "$sl", ...). Any ordinary or completed key ends this phase.
+          // Prefixes come from the evaluator's directive registry.
+          if: starterObject,
+          then: {
+            properties: Object.fromEntries(
+              Object.entries(specs).map(([key2, spec]) => [
+                key2,
+                share(spec.properties[key2])
+              ])
+            )
+          }
+        }
+      ]
+    };
+    return { ...self, ...annotations };
+  }
+  definitions[bodyName] = author(componentRef, true);
+  return ref(bodyName);
+}
+
+// src/blocks/compose.ts
+async function composeBlocksWithPlugins(evaluator, document, options) {
+  const preserve = options.preserve ?? /* @__PURE__ */ new Set();
+  let visited = 0;
+  const walk = async (value, path, depth) => {
+    if (depth > 64 || ++visited > 1e5)
+      throw new BlockEvaluationError([
+        {
+          path: toAuthoredBlockPointer(evaluator.sourceMap, path),
+          code: "block_expansion_limit",
+          message: "Combined plugin/block expansion exceeds depth/node limits (64/100000)."
+        }
+      ]);
+    if (Array.isArray(value)) {
+      const children = [];
+      for (let i = 0; i < value.length; i++)
+        children.push(await walk(value[i], `${path}/${i}`, depth + 1));
+      return {
+        standard: children.map((c) => c.standard),
+        preserved: children.map((c) => c.preserved)
+      };
+    }
+    if (!isBlockRecord(value) || value.enabled === false)
+      return { standard: value, preserved: value };
+    if (value.name === "block")
+      return walk(evaluator.expand(value, path, depth), path, depth + 1);
+    const standard = { ...value };
+    const kept = { ...value };
+    for (const [key, item] of Object.entries(value)) {
+      if (path === "/props" && key === "blocks") continue;
+      const processed = await walk(item, `${path}/${key}`, depth + 1);
+      Object.defineProperty(standard, key, {
+        value: processed.standard,
+        enumerable: true,
+        configurable: true,
+        writable: true
+      });
+      Object.defineProperty(kept, key, {
+        value: processed.preserved,
+        enumerable: true,
+        configurable: true,
+        writable: true
+      });
+    }
+    if (typeof value.name === "string" && options.plugins.has(value.name)) {
+      const source = toAuthoredBlockPointer(evaluator.sourceMap, path);
+      const emitted = await options.render(standard, source);
+      evaluator.sourceMap[`${path}/children`] = source;
+      const processed = await walk(emitted, `${path}/children`, depth + 1);
+      return {
+        standard: { name: "group", children: processed.standard },
+        preserved: preserve.has(value.name) ? value : { name: "group", children: processed.preserved }
+      };
+    }
+    return { standard, preserved: kept };
+  };
+  return walk(document, "", 0);
+}
+
+// src/blocks/editor.ts
+import { Value as Value3 } from "@sinclair/typebox/value";
+var clone = (value) => JSON.parse(JSON.stringify(value));
+function range(minimum, maximum, unit) {
+  if (minimum !== void 0 && maximum !== void 0)
+    return minimum === maximum ? `${minimum} ${unit}` : `${minimum}\u2013${maximum} ${unit}`;
+  if (minimum !== void 0) return `at least ${minimum} ${unit}`;
+  if (maximum !== void 0) return `at most ${maximum} ${unit}`;
+  return void 0;
+}
+function blockSlotFacts(slot) {
+  const facts = [];
+  if (slot.required && slot.default === void 0) facts.push("Required");
+  if (slot.default !== void 0)
+    facts.push(`Default: \`${JSON.stringify(slot.default)}\``);
+  if (slot.type === "component")
+    facts.push("A component; placement stays in the definition");
+  if (slot.enum)
+    facts.push(
+      `One of ${slot.enum.map((value) => `\`${JSON.stringify(value)}\``).join(", ")}`
+    );
+  const length = range(slot.minLength, slot.maxLength, "characters");
+  if (length) facts.push(length);
+  if (slot.maxWords !== void 0) facts.push(`at most ${slot.maxWords} words`);
+  if (slot.oneLine) facts.push("one line");
+  const bounds = range(slot.minimum, slot.maximum, "");
+  if (bounds) facts.push(bounds.trim());
+  const entries = range(slot.minItems, slot.maxItems, "entries");
+  if (entries) facts.push(entries);
+  if (slot.role) facts.push(`Role: ${slot.role}`);
+  return facts;
+}
+function blockSlotMarkdown(slot) {
+  return [slot.description, blockSlotFacts(slot).join(" \xB7 ")].filter(Boolean).join("\n\n");
+}
+function blockSlotEditorSchema(slot, componentRef) {
+  let schema;
+  if (slot.type === "component") {
+    schema = componentRef ? {
+      allOf: [
+        componentRef,
+        {
+          properties: {
+            props: {
+              propertyNames: {
+                not: { enum: [...BLOCK_SLOT_PLACEMENT_PROPS] },
+                errorMessage: "Block placement belongs in the definition, not in a component slot."
+              }
+            }
+          }
+        }
+      ]
+    } : {
+      type: "object",
+      properties: { name: { type: "string" } },
+      required: ["name"]
+    };
+  } else {
+    const { oneLine, properties, items, ...rest } = slot;
+    for (const key of ["role", "required", "maxWords", "description"])
+      delete rest[key];
+    schema = { ...rest };
+    if (oneLine) schema.pattern = "^[^\\r\\n]*$";
+    if (items) schema.items = blockSlotEditorSchema(items, componentRef);
+    if (properties) {
+      schema.properties = Object.fromEntries(
+        Object.entries(properties).map(([key, value]) => [
+          key,
+          blockSlotEditorSchema(value, componentRef)
+        ])
+      );
+      schema.required = Object.entries(properties).filter(([, value]) => value.required && value.default === void 0).map(([key]) => key);
+      schema.additionalProperties = false;
+    }
+  }
+  if (slot.description) schema.description = slot.description;
+  const markdown = blockSlotMarkdown(slot);
+  if (markdown) schema.markdownDescription = markdown;
+  return schema;
+}
+function blockSlotsEditorSchema(definition, componentRef) {
+  return {
+    type: "object",
+    additionalProperties: false,
+    description: "Input values keyed by the slot names declared in the referenced block definition.",
+    properties: Object.fromEntries(
+      Object.entries(definition.slots).map(([key, slot]) => [
+        key,
+        blockSlotEditorSchema(slot, componentRef)
+      ])
+    ),
+    required: Object.entries(definition.slots).filter(([, slot]) => slot.required && slot.default === void 0).map(([key]) => key)
+  };
+}
+function blockInvocationPropsSchema(definitions, componentRef) {
+  const names = Object.keys(definitions);
+  const schema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["ref"],
+    properties: {
+      ref: {
+        type: "string",
+        minLength: 1,
+        description: "Name in this document\u2019s props.blocks.",
+        ...names.length && {
+          anyOf: names.map((name) => ({
+            const: name,
+            type: "string",
+            description: definitions[name].description ?? `Block "${name}", defined in this document.`
+          }))
+        }
+      },
+      slots: {
+        type: "object",
+        description: "Input values keyed by the slot names declared in the referenced block definition."
+      }
+    }
+  };
+  if (names.length)
+    schema.allOf = names.map((name) => ({
+      if: { properties: { ref: { const: name } }, required: ["ref"] },
+      then: {
+        properties: {
+          slots: blockSlotsEditorSchema(definitions[name], componentRef)
+        }
+      }
+    }));
+  return schema;
+}
+function applyDocumentBlocksToSchema(schema, definitions, targets) {
+  for (const target of targets) {
+    const definition = schema.definitions?.[target.name];
+    if (!definition) continue;
+    const props = blockInvocationPropsSchema(definitions, target.componentRef);
+    const seen = /* @__PURE__ */ new Set();
+    const walk = (node) => {
+      if (!node || typeof node !== "object" || seen.has(node)) return;
+      seen.add(node);
+      if (Array.isArray(node)) {
+        node.forEach(walk);
+        return;
+      }
+      const value = node;
+      if (value.properties?.name?.const === "block" && value.properties.props) {
+        value.properties.props = clone(props);
+        return;
+      }
+      for (const [key, child] of Object.entries(value))
+        if (key !== "$ref") walk(child);
+    };
+    walk(definition);
+  }
+}
+function invocations(node, visit) {
+  if (Array.isArray(node)) {
+    node.forEach((item) => invocations(item, visit));
+    return;
+  }
+  if (!isBlockRecord(node)) return;
+  if (node.name === "block" && isBlockRecord(node.props) && typeof node.props.ref === "string")
+    visit(node.props.ref, node);
+  for (const value of Object.values(node)) invocations(value, visit);
+}
+function blockDependencies(definitions, name) {
+  const order = [];
+  const seen = /* @__PURE__ */ new Set([name]);
+  const walk = (current) => {
+    const definition = Object.prototype.hasOwnProperty.call(
+      definitions,
+      current
+    ) ? definitions[current] : void 0;
+    if (!definition) return;
+    invocations(
+      [definition.body, definition.section, definition.slide],
+      (ref) => {
+        if (seen.has(ref)) return;
+        seen.add(ref);
+        if (!Object.prototype.hasOwnProperty.call(definitions, ref)) return;
+        walk(ref);
+        order.push(ref);
+      }
+    );
+  };
+  walk(name);
+  return order;
+}
+function exampleValue(slot, name, format) {
+  if (slot.default !== void 0) return clone(slot.default);
+  if (slot.enum?.length) return slot.enum[0];
+  switch (slot.type) {
+    case "string":
+      return name;
+    case "number":
+    case "integer": {
+      const minimum = slot.minimum ?? 0;
+      return slot.maximum !== void 0 && slot.maximum < minimum ? slot.maximum : minimum;
+    }
+    case "boolean":
+      return true;
+    case "array": {
+      const count = Math.min(
+        Math.max(3, slot.minItems ?? 0),
+        slot.maxItems ?? Number.POSITIVE_INFINITY
+      );
+      const item = slot.items ?? { type: "string" };
+      return Array.from(
+        { length: count },
+        (_, index) => exampleValue(item, `${name} ${index + 1}`, format)
+      );
+    }
+    case "object":
+      return exampleSlots(slot.properties ?? {}, format);
+    case "component":
+      return format === "docx" ? { name: "paragraph", props: { text: name } } : { name: "text", props: { text: name } };
+    default:
+      return name;
+  }
+}
+function exampleSlots(slots, format) {
+  return Object.fromEntries(
+    Object.entries(slots).filter(
+      ([, slot]) => slot.required && slot.default === void 0 || slot.role
+    ).map(([key, slot]) => [key, exampleValue(slot, key, format)])
+  );
+}
+function blockInvocationExample(name, definition, options) {
+  let found;
+  if (isBlockRecord(options.document)) {
+    const authored = Object.fromEntries(
+      Object.entries(options.document).filter(([key]) => key !== "props")
+    );
+    invocations(authored, (ref, invocation) => {
+      if (found || ref !== name) return;
+      const props = invocation.props;
+      found = {
+        name: "block",
+        props: {
+          ref,
+          ...isBlockRecord(props.slots) && { slots: clone(props.slots) }
+        }
+      };
+    });
+  }
+  return found ?? {
+    name: "block",
+    props: {
+      ref: name,
+      slots: exampleSlots(definition.slots, options.format)
+    }
+  };
+}
+function blockReferencesFromDocument(document, source) {
+  const definitions = readBlockDefinitions(document);
+  if (!Value3.Check(BlockDefinitionsSchema, definitions) || validateBlockDefinitions(definitions, source.format).length > 0)
+    return [];
+  return Object.entries(definitions).map(([name, definition]) => ({
+    name,
+    format: source.format,
+    template: source.template,
+    definitionPointer: `/props/blocks/${blockPointerKey(name)}`,
+    description: definition.description ?? "",
+    definition,
+    slotsSchema: blockSlotsJsonSchema(definition),
+    example: blockInvocationExample(name, definition, {
+      document,
+      format: source.format
+    }),
+    dependencies: blockDependencies(definitions, name)
+  }));
+}
+
 // src/utils/deepMerge.ts
 function isObject(item) {
   return item !== null && typeof item === "object" && !Array.isArray(item);
@@ -1508,6 +3352,12 @@ function mergeWithDefaults(userConfig, themeDefaults) {
   return deepMerge(themeDefaults, userConfig);
 }
 export {
+  BLOCK_SLOT_PLACEMENT_PROPS,
+  BLOCK_SLOT_ROLES,
+  BlockDefinitionsSchema,
+  BlockEvaluationError,
+  BlockInvocationPropsSchema,
+  BlockSlotSchema,
   CANVASES,
   ChromeSchema,
   ComponentValidationError,
@@ -1526,6 +3376,8 @@ export {
   FontRegistryEntrySchema,
   FontRegistrySchema,
   FontSourceSchema,
+  JsonBlockDefinitionSchema,
+  JsonBlockEvaluator,
   MAX_RASTERIZE_BATCH_SLIDES,
   MAX_RASTERIZE_FONTS,
   MAX_RASTERIZE_FONT_BYTES,
@@ -1549,10 +3401,26 @@ export {
   UnknownPreservedComponentError,
   UnsupportedRendererFeatureError,
   WEIGHT_LABELS,
+  applyDocumentBlocksToSchema,
   applyExportMode,
   applyFontSubstitution,
   assertNever,
   assertRendererSupports,
+  blockDependencies,
+  blockInvocationExample,
+  blockInvocationPropsSchema,
+  blockPointerKey,
+  blockReferencesFromDocument,
+  blockSlotBudgets,
+  blockSlotEditorSchema,
+  blockSlotFacts,
+  blockSlotJsonSchema,
+  blockSlotMarkdown,
+  blockSlotRoles,
+  blockSlotsEditorSchema,
+  blockSlotsJsonSchema,
+  blockValueAt,
+  blockWordCount,
   buildDefaultSubstitutionMap,
   calculatePosition,
   capsFormatting,
@@ -1564,7 +3432,9 @@ export {
   collectFontNamesFromDocx,
   collectFontNamesFromPptx,
   compareSemver,
+  composeBlocksWithPlugins,
   convertToJsonSchema,
+  createBlockAuthoringSchema,
   createComponent,
   createComponentSchema,
   createComponentSchemaObject,
@@ -1577,6 +3447,7 @@ export {
   designColors,
   detectFontFormat,
   diagnoseUnsupportedFeatures,
+  documentBlockMetadata,
   documentFontRegistry,
   exportSchemaToFile,
   extractStandardComponentNames,
@@ -1591,6 +3462,7 @@ export {
   getValidationSummary,
   groupErrorsByPath,
   isAllowedFontUrl,
+  isBlockRecord,
   isLiteralSchema,
   isObjectSchema,
   isSafeFont,
@@ -1602,8 +3474,10 @@ export {
   mergeWithDefaults,
   parseSemver,
   partitionDiagnostics,
+  readBlockDefinitions,
   rendererError,
   rendererWarning,
+  resolveBlockSlot,
   resolveComponentVersion,
   resolveDesignColor,
   resolveTypeRoles,
@@ -1611,9 +3485,12 @@ export {
   rewriteFontFamilyName,
   synthesizeFamilyName,
   themeFontRegistry,
+  toAuthoredBlockPointer,
   transformValueError,
   transformValueErrors,
   unionBranches,
+  validateBlockDefinitions,
+  validateBlockInvocations,
   validateCustomComponentProps,
   validateDesignColors,
   validateFontReferences,