@openpresentation/opf 0.15.1 → 0.16.0

package/dist/{chunk-QDI75P2M.js → chunk-PX5AWL7Y.js}

@@ -1,7 +1,7 @@
-import { promotedRegionKeys, VARIABLE_KINDS, resolveChartData, chartPaletteForFill, imageBackground, tableGrid, timelineTextColor, visitContentPayloads, readingRows, visualReadingOrder, intrinsicImageSize, textWidthMeasurer, normalizeHexColor, resolveColorRef, resolveDesignRecords, resolveColorRoles, resolveFontFamilies, resolveCanvasDimensions, defaultSlideBackground, isRecord, hasContentVariables, isTemplate, instantiateForValidation, unusedDatasets, MAX_COMPOSITION_DEPTH, datasetDiagnostics, pathFor, collectCitations, numberingFindings, walkCitationRuns, resolveTableData, resolveChartOptions, chartOptionTarget, codeHighlightLines, chartNumberFixesByCell, OPFCompositionError, composeSlide, resolveScriptFonts } from './chunk-O744SXXA.js';
+import { promotedRegionKeys, VARIABLE_KINDS, resolveChartData, chartPaletteForFill, imageBackground, tableGrid, timelineTextColor, visitContentPayloads, readingRows, visualReadingOrder, intrinsicImageSize, textWidthMeasurer, normalizeHexColor, resolveColorRef, resolveDesignRecords, resolveColorRoles, resolveFontFamilies, resolveCanvasDimensions, defaultSlideBackground, isRecord, hasContentVariables, isTemplate, instantiateForValidation, unusedDatasets, MAX_COMPOSITION_DEPTH, datasetDiagnostics, pathFor, collectCitations, numberingFindings, walkCitationRuns, resolveTableData, resolveChartOptions, chartOptionTarget, codeHighlightLines, chartNumberFixesByCell, MAX_PLACEHOLDER_GROUP_DEPTH, OPFCompositionError, composeSlide, resolveScriptFonts } from './chunk-5PDN7BN6.js';
 import { catalogSchemaNames } from './chunk-TRDXRRQK.js';
 import { resolveReference, checkCatalogsOption, provenanceOf, unresolvedReference, OPFUnresolvedReferenceError, catalogReferenceSites, parseReference, catalogGroupDeclared, pointerPath, catalogRecords, catalogKinds, catalogGroupSource, registeredCatalog } from './chunk-SPFV27O5.js';
-import { schemaEntries, schemas } from './chunk-2CJPC4HI.js';
+import { schemaEntries, schemas } from './chunk-WEDGVC5W.js';
 import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 import { parseTree, printParseErrorCode, getNodePath } from 'jsonc-parser';
@@ -864,6 +864,33 @@ function dataUnionErrors(errors, value) {
     return { ...error, message: field === "fields" ? "'fields' applies only to a dataset-backed table; add 'dataset' or remove 'fields'" : datasetTableMessage(field) };
   });
 }
+var placeholderHeadings = /* @__PURE__ */ new Set(["title", "subtitle", "tag"]);
+function placeholderGroupIssues(value) {
+  const issues = [];
+  if (!isRecord(value) || !Array.isArray(value.placeholders)) return issues;
+  const walk = (entries, path, depth) => entries.forEach((entry, index) => {
+    if (!isRecord(entry)) return;
+    const at2 = `${path}/${index}`;
+    if (entry.type === "group") {
+      if (depth >= MAX_PLACEHOLDER_GROUP_DEPTH) issues.push(semanticIssue(at2, `placeholder groups nest at most ${MAX_PLACEHOLDER_GROUP_DEPTH} levels inside a layout record; this group would be level ${depth + 1}`, { code: "layout-placeholder-group", depth: depth + 1, maxDepth: MAX_PLACEHOLDER_GROUP_DEPTH }));
+      else if (Array.isArray(entry.placeholders)) walk(entry.placeholders, `${at2}/placeholders`, depth + 1);
+      return;
+    }
+    if (depth === 0) return;
+    if (typeof entry.type === "string" && placeholderHeadings.has(entry.type)) issues.push(semanticIssue(`${at2}/type`, `a placeholder group holds body regions only; a '${entry.type}' placeholder belongs at the record's top level`, { code: "layout-placeholder-group" }));
+    if (hasOwn(entry, "placement")) issues.push(semanticIssue(`${at2}/placement`, "placement is only valid on a top-level image placeholder; a region inside a placeholder group cannot bleed to a slide edge", { code: "image-placement-invalid" }));
+  });
+  walk(value.placeholders, "/placeholders", 0);
+  return issues;
+}
+function withPlaceholderGroupIssues(errors, value) {
+  const issues = placeholderGroupIssues(value);
+  const entries = issues.map((issue2) => issue2.path.replace(/\/(type|placement)$/, ""));
+  const covered = (error) => entries.some((entry) => error.path === entry || error.path.startsWith(`${entry}/`));
+  const kept = errors.filter((error) => !covered(error));
+  const reported = [...kept.filter((error) => error.keyword !== "if"), ...issues].map((error) => error.path);
+  return [...kept.filter((error) => error.keyword !== "if" || !reported.some((path) => path === error.path || path.startsWith(`${error.path}/`))), ...issues];
+}
 function validateAgainstSchema(value, schemaOrKind = "presentation", options = {}) {
   const resolved = resolveValidator(schemaOrKind);
   if (resolved.schemaName === "presentation") {
@@ -895,7 +922,8 @@ function validateAgainstSchema(value, schemaOrKind = "presentation", options = {
   }
   const valid = resolved.validate(subject) === true;
   const ajvErrors = valid ? [] : typedVariableErrors(resolved.validate.errors ?? [], subject);
-  const errors = (resolved.schemaName === "presentation" ? dataUnionErrors(ajvErrors, subject) : ajvErrors).map(toIssue);
+  const mapped = (resolved.schemaName === "presentation" ? dataUnionErrors(ajvErrors, subject) : ajvErrors).map(toIssue);
+  const errors = resolved.schemaName === "layout" ? withPlaceholderGroupIssues(mapped, subject) : mapped;
   const warnings = [];
   if (resolved.schemaName === "presentation") {
     errors.push(...presentationSemanticIssues(subject));
@@ -1918,7 +1946,7 @@ var languageRule = rule(
   "info",
   "The presentation does not declare its language.",
   "Screen readers and text-to-speech choose pronunciation and hyphenation from the declared language; spell checkers and translation tools use it too.",
-  { standard: "WCAG 2.2 SC 3.1.1 Language of Page, level A", approximations: "Only the presentation-level `language` is checked, not the language of individual runs (OPF has no per-run language)." }
+  { standard: "WCAG 2.2 SC 3.1.1 Language of Page, level A", approximations: "Only the presentation-level `language` is checked, not the language of individual runs (`TextRun.lang`; opf/language-tag checks how those tags are written)." }
 );
 var languageRules = [
   {
@@ -1944,6 +1972,105 @@ var accessibilityRules = [
   ...languageRules
 ];
 
+// src/language-tag.ts
+var REGION_ALIASES = { UK: "GB" };
+var privateRegion = /^(?:AA|Q[M-Z]|X[A-Z]|ZZ)$/;
+var regionNames;
+var assignedRegion = (region) => {
+  if (privateRegion.test(region)) return true;
+  regionNames ??= new Intl.DisplayNames(["en"], { type: "region", fallback: "code" });
+  try {
+    return regionNames.of(region) !== region;
+  } catch {
+    return false;
+  }
+};
+var canonical = (tag) => {
+  try {
+    return Intl.getCanonicalLocales(tag)[0];
+  } catch {
+    return void 0;
+  }
+};
+function regionSubtag(tag) {
+  const subtags = tag.split("-");
+  for (let index = 1; index < subtags.length; index++) {
+    const subtag = subtags[index];
+    if (/^(?:[a-z]{2}|\d{3})$/i.test(subtag)) return { region: subtag.toUpperCase(), index };
+    if (!/^[a-z]{3,4}$/i.test(subtag)) return void 0;
+  }
+  return void 0;
+}
+function languageTagProblem(tag) {
+  if (/^[ix]-/i.test(tag)) return void 0;
+  const parsed = canonical(tag);
+  if (parsed === void 0) return { message: `'${tag}' is not a well-formed BCP 47 language tag (subtags are letters and digits joined by hyphens, such as 'en-US' or 'zh-Hans').`, caseOnly: false };
+  const found = regionSubtag(tag);
+  if (found) {
+    const alias = REGION_ALIASES[found.region];
+    if (alias || !assignedRegion(found.region)) {
+      const subtags = tag.split("-");
+      subtags[found.index] = alias ?? found.region;
+      const suggestion = alias ? canonical(subtags.join("-")) : void 0;
+      return {
+        message: `'${tag}' names the region '${found.region}', which is not an assigned region${suggestion ? `; '${suggestion}' is the tag for ${new Intl.DisplayNames(["en"], { type: "region" }).of(alias)}` : ""}.`,
+        ...suggestion ? { suggestion } : {},
+        caseOnly: false
+      };
+    }
+  }
+  if (parsed === tag) return void 0;
+  if (parsed.toLowerCase() === tag.toLowerCase())
+    return { message: `'${tag}' is not in canonical case; the canonical form is '${parsed}' (language lower case, script title case, region upper case).`, suggestion: parsed, caseOnly: true };
+  const replacement = found && regionSubtag(parsed)?.region;
+  if (found && replacement && replacement !== found.region) {
+    const subtags = tag.split("-");
+    subtags[found.index] = replacement;
+    return { message: `'${tag}' names the region '${found.region}', which is deprecated; use '${replacement}'.`, suggestion: subtags.join("-"), caseOnly: false };
+  }
+  return void 0;
+}
+
+// src/rules-language.ts
+var languageTagRule = rule(
+  "language-tag",
+  "content",
+  "warning",
+  "A language tag is malformed, uses an unassigned region or is not in canonical case.",
+  "Engines read the deck language and each run's `lang` as BCP 47 tags to choose script fonts, text direction, proofing language and the PowerPoint `lang` attribute. A tag such as `en-a`, or a region that does not exist (`en-UK`; the United Kingdom is `GB`), is guessed at or dropped, and a wrong-case tag (`EN-us`) is not what a locale lookup expects.",
+  {
+    standard: "BCP 47 (RFC 5646, section 2.1) and the platform locale data (Intl.getCanonicalLocales, Intl.DisplayNames)",
+    approximations: "Checks the root `language` (a tag string, or the `bcp47` of an inline Language object) and `lang` on the TextRun objects of titles, subtitles, tags, text, lists, tables, quotes, metrics and timelines. A region is assigned when the runtime's CLDR data names it (ISO 3166-1 codes and UN M.49 areas such as 419); private-use regions (`AA`, `QM`-`QZ`, `XA`-`XZ`) and `ZZ` are accepted, as are private-use (`x-...`) tags. Only the spelling of a tag is checked, not whether the language subtag is assigned or whether the language suits the text. The schema rejects tags with characters other than letters, digits and hyphens (`en_US` is a schema error, with no suggestion), and `en-UK` as the deck language is already an error of the schema rule, so those are not reported twice."
+  }
+);
+var report = (context, tag, path, slide) => {
+  if (typeof tag !== "string") return;
+  const problem = languageTagProblem(tag);
+  if (!problem) return;
+  context.report(languageTagRule, {
+    path,
+    slide,
+    message: problem.message,
+    help: problem.suggestion ? `Write '${problem.suggestion}'.` : 'Write a well-formed BCP 47 tag with an assigned region, such as "en-US", "pt-BR" or "es-419".',
+    ...problem.suggestion ? { fixes: [{ id: "use-canonical-tag", title: `Use '${problem.suggestion}'`, kind: "patch", safe: problem.caseOnly, patch: [{ op: "replace", path, value: problem.suggestion }] }] } : {}
+  });
+};
+var isEnUk = (tag) => typeof tag === "string" && tag.toLowerCase() === "en-uk";
+var languageTagRules = [
+  {
+    info: languageTagRule,
+    run(context) {
+      const language = context.document.language;
+      if (typeof language === "string") {
+        if (!isEnUk(language)) report(context, language, "/language");
+      } else if (language !== void 0 && !isEnUk(rec(language).bcp47)) report(context, rec(language).bcp47, "/language/bcp47");
+      for (const slide of context.slides)
+        for (const tv of slide.texts)
+          if (typeof tv.value !== "string") for (const run of runsOf(tv)) report(context, run.style.lang, `${run.path}/lang`, slide);
+    }
+  }
+];
+
 // src/rules-layout-content.ts
 var PX_TO_PT2 = 0.75;
 var round2 = (value, places = 1) => Math.round(value * 10 ** places) / 10 ** places;
@@ -2287,6 +2414,7 @@ var formatRules = [
   rule("caption-unsupported-payload", "format", "error", "A caption is on a payload that cannot carry one.", "A caption belongs to exactly one image, chart, table or video; a group, text or code block has no place to draw it.", { standard: SCHEMA }),
   rule("image-option-unsupported-payload", "format", "error", "An image option is on a payload that is not an image.", "`fit`, `focus`, the image treatments (`shape`, `cornerRadius`, `border`, `opacity`, `recolor`, `overlay`, `aspectRatio`) and `placement` describe how a picture is drawn; a group, text or chart block has no picture for them to apply to.", { standard: SCHEMA }),
   rule("image-placement-invalid", "format", "error", "An image placement cannot be honoured.", "A placed image bleeds to a slide edge and the rest of the slide composes beside it. Only a top-level block (slides.N.blocks.I) can do that, and a slide edge holds one placed image; a block in a group or a promoted region, or a second block on the same edge, has nowhere to go.", { standard: SCHEMA }),
+  rule("layout-placeholder-group", "format", "error", "A layout record's placeholder group breaks a nesting rule.", "A placeholder group arranges body regions inside one cell of its layout record. Groups nest at most three levels inside a record, and a group holds body regions and groups only: the headings (title, subtitle, tag) stay at the record's top level, where the engine places them. Composition cannot use a record that breaks either rule.", { standard: SCHEMA }),
   rule("dataset-unknown", "format", "error", "A chart or table names a dataset that does not exist.", "The data cannot be drawn without the dataset it refers to.", { standard: SCHEMA }),
   rule("dataset-field-unknown", "format", "error", "A table asks a dataset for a column it does not have.", "The column cannot be shown when the dataset has no column of that name.", { standard: SCHEMA }),
   rule("data-column-duplicate", "format", "error", "A dataset or table has two columns with the same name.", "Series, mappings and fields address columns by name, so a repeated name makes them ambiguous.", { standard: SCHEMA }),
@@ -2381,7 +2509,7 @@ var dataRules = [
   rule("duration-outside-narrative", "content", "warning", "The target duration is outside the range the narrative suits.", "A narrative records the talk lengths it suits. A deck whose duration is outside that range probably needs a different narrative or a different length; nothing is drawn or exported differently.", { standard: SCHEMA }),
   rule("narrative-duration-range", "content", "warning", "An inline narrative duration range has min greater than max.", "A range with its bounds swapped matches no duration, so the duration check cannot help.", { standard: "spec/schemas/narrative.schema.json" })
 ];
-var implementations = [...accessibilityRules, ...layoutContentRules];
+var implementations = [...accessibilityRules, ...layoutContentRules, ...languageTagRules];
 var ruleImplementations = implementations;
 var infos = [
   ...formatRules,
@@ -3248,12 +3376,12 @@ var OPFValidationError = class extends Error {
   report;
   /** The error-severity findings of the report. */
   findings;
-  constructor(report) {
-    const errors = report.findings.filter((entry) => entry.severity === "error");
+  constructor(report2) {
+    const errors = report2.findings.filter((entry) => entry.severity === "error");
     const first = errors[0];
     super(first ? `OPF validation failed at ${first.path || "/"}: ${first.message}` : "OPF validation failed");
     this.name = "OPFValidationError";
-    this.report = report;
+    this.report = report2;
     this.findings = errors;
   }
 };
@@ -3486,8 +3614,8 @@ function validate(input, options = {}) {
 }
 function assertValid(value, options = {}) {
   if (typeof value === "string") throw new TypeError("assertValid takes a parsed presentation. Use validate(text) for JSON text.");
-  const report = validate(value, options);
-  if (!report.valid) throw new OPFValidationError(report);
+  const report2 = validate(value, options);
+  if (!report2.valid) throw new OPFValidationError(report2);
 }
 function validateCatalogRecord(kind, value) {
   const kinds = Object.keys(catalogSchemaNames);
@@ -3508,8 +3636,8 @@ function validateCatalogRecord(kind, value) {
   return { valid: tally.error === 0, schemaValid: engine.valid, findings, counts: tally, checks };
 }
 function assertValidCatalogRecord(kind, value) {
-  const report = validateCatalogRecord(kind, value);
-  if (!report.valid) throw new OPFValidationError(report);
+  const report2 = validateCatalogRecord(kind, value);
+  if (!report2.valid) throw new OPFValidationError(report2);
 }
 
-export { DEFAULT_CHART_PALETTE, DEFAULT_VALIDATION_THRESHOLDS, OPFValidationError, assertValid, assertValidCatalogRecord, findValidationRule, resolveSlideContext, validate, validateCatalogRecord, validationCategories, validationRules };
+export { DEFAULT_CHART_PALETTE, DEFAULT_VALIDATION_THRESHOLDS, OPFValidationError, assertValid, assertValidCatalogRecord, findValidationRule, parseSource, resolveSlideContext, validate, validateCatalogRecord, validationCategories, validationRules };

package/dist/{chunk-U4J75TRG.js → chunk-SMLMI6IZ.js}

@@ -1,4 +1,4 @@
-import { chartNumber } from './chunk-O744SXXA.js';
+import { chartNumber } from './chunk-5PDN7BN6.js';
 
 // src/data.ts
 var OPFDataImportError = class extends Error {
@@ -138,7 +138,10 @@ function importData(input, options) {
     if (circular && numeric < 0) fail(`Row ${i + 1}: pie and donut values cannot be negative.`);
     return numeric;
   }));
-  return { chart: { type: options.chartType ?? "column", data: { columns: names, rows } } };
+  return { chart: { type: options.chartType ?? "column", data: {
+    columns: names,
+    rows
+  } } };
 }
 
 export { OPFDataImportError, importData, parseTabularData };

package/dist/{chunk-TWQJLI6E.js → chunk-UM24JFUE.js}

@@ -1,5 +1,5 @@
-import { jsonEqual, formatPointer } from './chunk-5FTUIDUH.js';
-import { annotationText } from './chunk-O744SXXA.js';
+import { jsonEqual, formatPointer } from './chunk-3XDRQYWZ.js';
+import { annotationText } from './chunk-5PDN7BN6.js';
 
 // src/diff-match.ts
 var DEFAULT_MATCH_THRESHOLD = 0.5;

package/dist/{chunk-2CJPC4HI.js → chunk-WEDGVC5W.js}

@@ -1217,7 +1217,7 @@ var presentation = {
             "left",
             "right"
           ],
-          "description": "Where the primary chart sits relative to supporting content. Effective value: slide design, then deck design, then the layout record's design.chartPrimary. When the slide has no promoted regions and no composition.mode of its own, and its root nodes mix at least one chart with other content, the first chart becomes a primary track and the other nodes form one synthetic sub-grid: 'left'/'right' is a two-track row and 'top'/'bottom' a two-track column, weighted 3:2 in favor of the chart; explicit root columns and weights are ignored while it applies. 'none' (the default) keeps the ordinary automatic grid with equal weight."
+          "description": "Where the primary chart sits relative to supporting content. Effective value: slide design, then deck design, then the layout record's design.chartPrimary. When the slide has no promoted regions and no composition.mode of its own, and its root nodes mix at least one chart with other content, the first chart becomes a primary track and the other nodes form one synthetic sub-grid: 'left'/'right' is a two-track row and 'top'/'bottom' a two-track column, weighted 3:2 in favor of the chart; explicit root columns and weights are ignored while it applies. 'none' (the default) keeps the ordinary automatic grid with equal weight. It is shorthand for a placeholder group (layout.schema.json PlaceholderGroup): the slide composes exactly as on a layout record whose root composition is that weighted row or column and whose placeholders are the chart and one automatic group of the other content, and while it applies it replaces the layout record's own placeholder groups as well."
         },
         "imageFit": {
           "type": "string",
@@ -2846,14 +2846,14 @@ var presentation = {
           "items": {
             "$ref": "#/$defs/ListItem"
           },
-          "description": "Full-slide generic list payload. Presence of this field infers type 'list'. At slide root, multiple content payload kinds with no explicit type, blocks, or regions are accepted as shorthand for layout-agnostic blocks."
+          "description": "Full-slide structured list payload. Presence of this field infers type 'list'. Entries are strings, TextRun[] or objects with `text`, optional `description` (supporting detail under the entry), `level` and `start`. Use `items` when entries share a shape (features, steps, options, risks) or any entry needs a `description`; use `bullets` for plain talking points. Both draw the same marker, nesting and numbering; they differ in the inferred kind and in `description`, which only `items` accepts. At slide root, multiple content payload kinds with no explicit type, blocks, or regions are accepted as shorthand for layout-agnostic blocks, so `items` next to `text` or `bullets` composes as separate blocks side by side."
         },
         "bullets": {
           "type": "array",
           "items": {
             "$ref": "#/$defs/BulletItem"
           },
-          "description": "Full-slide text-style bullet payload. Presence of this field infers type 'text'."
+          "description": "Full-slide prose bullet payload: short talking points, each standing alone. Presence of this field infers type 'text', so it may sit beside `text` in one payload. Entries are strings, TextRun[] or objects with `text`, `level` and `start`; there is no `description` (use `items` for entries with supporting detail)."
         },
         "numbering": {
           "$ref": "#/$defs/NumberingSpec",
@@ -3187,7 +3187,7 @@ var presentation = {
           "items": {
             "$ref": "#/$defs/ListItem"
           },
-          "description": "Generic list payload. Each item is either a plain string, a TextRun[] rich text sequence, or a ListItem object. List nesting uses item.level rather than nested content payloads.",
+          "description": "Structured list payload (type 'list'). Each item is either a plain string, a TextRun[] rich text sequence, or a ListItem object with optional `description`. List nesting uses item.level rather than nested content payloads. Use `items` when entries share a shape or any entry needs a `description`; use `bullets` for plain talking points. Both draw the same marker, nesting and numbering. A block or region holds `items` or `bullets`, never both, and `items` cannot sit beside `text`.",
           "examples": [
             [
               "Sub-second agent latency",
@@ -3210,7 +3210,7 @@ var presentation = {
           "items": {
             "$ref": "#/$defs/BulletItem"
           },
-          "description": "Text-style bullet payload. Presence of this field infers type 'text'.",
+          "description": "Prose bullet payload: short talking points, each standing alone. Presence of this field infers type 'text', so it may sit beside `text` in one payload. Entries have no `description`; use `items` for entries with supporting detail.",
           "examples": [
             [
               "Sub-second agent latency",
@@ -4822,6 +4822,13 @@ var presentation = {
         "fields": {
           "$ref": "#/$defs/DatasetFields",
           "description": "Dataset tables only: the dataset columns to show, by name and in order. Absent shows every column. An unknown name is a 'dataset-field-unknown' error."
+        },
+        "alt": {
+          "type": "string",
+          "description": "Text alternative for the table: what it shows (the point and the key numbers), not 'a table'. The preview exposes it as the table's accessible name (role group with aria-label; the cells stay readable) and the PowerPoint export writes it as the table frame's alternative text (descr); import reads it back. An empty string hides a purely decorative table, with the same meaning as an empty Asset alt. The alt is a summary read before the cells, which stay readable, so it is most useful for a large or dense table; validate does not require one and does not report a missing one.",
+          "examples": [
+            "North America grew 46% to $18.1M in Q4, ahead of EMEA at 40%."
+          ]
         }
       }
     },
@@ -5708,7 +5715,7 @@ var presentation = {
     "Composition": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Portable dynamic composition. Slide fields override the resolved layout. Nested groups arrange their children independently, inheriting only minFontSize and overflow. Explicit promoted regions retain their positions.",
+      "description": "Portable dynamic composition. Slide fields override the resolved layout. Nested groups (content groups here, placeholder groups in a layout record) arrange their children independently, inheriting only minFontSize and overflow. Explicit promoted regions retain their positions.",
       "properties": {
         "mode": {
           "type": "string",
@@ -6453,9 +6460,9 @@ var layout = {
     "placeholders": {
       "type": "array",
       "items": {
-        "$ref": "#/$defs/Placeholder"
+        "$ref": "#/$defs/PlaceholderEntry"
       },
-      "description": "Ordered regions the layout exposes. This is the single source of truth for what the layout holds: the content kind, the number of body regions and whether it has a title, subtitle or tag are derived from it (layoutContent in @openpresentation/opf), never stored separately. The engine fills 'title', 'subtitle' and 'tag' placeholders from Slide.title, Slide.subtitle and Slide.tag. The other placeholders are content-kind regions that composition uses to size the body and that pickers use to match layouts. Slide content itself lives either in root payload fields or promoted region keys on Slide. Chrome (slide number, footer, date) is not included here; it is owned by Design.header / Design.footer."
+      "description": `Ordered regions the layout exposes. This is the single source of truth for what the layout holds: the content kind, the number of body regions and whether it has a title, subtitle or tag are derived from it (layoutContent in @openpresentation/opf, which counts the leaves of placeholder groups), never stored separately. The engine fills 'title', 'subtitle' and 'tag' placeholders from Slide.title, Slide.subtitle and Slide.tag. The other placeholders are content-kind regions that composition uses to size the body and that pickers use to match layouts. An entry may instead be a placeholder group ({ "type": "group", "composition", "placeholders" }) that arranges its own regions inside one cell of this record's composition, so a record can say 'two stacked panels beside a chart' once; groups nest at most three levels. Slide content stays flat: its body payloads fill the leaf regions in reading order (depth first, in array order). Slide content itself lives either in root payload fields, blocks or promoted region keys on Slide. Chrome (slide number, footer, date) is not included here; it is owned by Design.header / Design.footer.`
     },
     "tags": {
       "type": "array",
@@ -6513,6 +6520,173 @@ var layout = {
     }
   },
   "$defs": {
+    "PlaceholderEntry": {
+      "description": "One entry of a layout's placeholders: a region (Placeholder) or, when its type is 'group', a placeholder group (PlaceholderGroup).",
+      "if": {
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "type": {
+            "const": "group"
+          }
+        }
+      },
+      "then": {
+        "$ref": "#/$defs/PlaceholderGroup"
+      },
+      "else": {
+        "$ref": "#/$defs/Placeholder"
+      }
+    },
+    "PlaceholderGroup": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "placeholders"
+      ],
+      "description": "A placeholder group: regions arranged by their own composition inside one cell of the record's composition, the way a content group (a block with blocks) arranges its children. Slide content fills the group's leaf regions in reading order, as part of one flat sequence for the whole record. A group holds body regions and groups only (no title, subtitle or tag, and no placement), and groups nest at most three levels inside a record: this is the first. Groups draw nothing of their own and have no slide path; design.chartPrimary is shorthand for a record whose root holds the chart and one group of the other content.",
+      "properties": {
+        "type": {
+          "const": "group",
+          "description": "Marks the entry as a placeholder group."
+        },
+        "composition": {
+          "$ref": "#/$defs/Composition",
+          "description": "How the group arranges its regions, with the semantics of a content group's composition: only minFontSize and overflow inherit from the enclosing composition; padding defaults to 0 and gap is a fraction of the group's short edge. Omitted, the group arranges its regions automatically."
+        },
+        "placeholders": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/PlaceholderGroupEntry2"
+          },
+          "description": "The group's regions and nested groups, in reading order."
+        }
+      }
+    },
+    "PlaceholderGroupEntry2": {
+      "description": "An entry of a first-level group: a region (GroupedPlaceholder) or a second-level group (PlaceholderGroup2).",
+      "if": {
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "type": {
+            "const": "group"
+          }
+        }
+      },
+      "then": {
+        "$ref": "#/$defs/PlaceholderGroup2"
+      },
+      "else": {
+        "$ref": "#/$defs/GroupedPlaceholder"
+      }
+    },
+    "PlaceholderGroup2": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "placeholders"
+      ],
+      "description": "A placeholder group nested in another (the second level). Same fields as PlaceholderGroup.",
+      "properties": {
+        "type": {
+          "const": "group",
+          "description": "Marks the entry as a placeholder group."
+        },
+        "composition": {
+          "$ref": "#/$defs/Composition",
+          "description": "How the group arranges its regions; see PlaceholderGroup.composition."
+        },
+        "placeholders": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/PlaceholderGroupEntry3"
+          },
+          "description": "The group's regions and nested groups, in reading order."
+        }
+      }
+    },
+    "PlaceholderGroupEntry3": {
+      "description": "An entry of a second-level group: a region (GroupedPlaceholder) or a third-level group (PlaceholderGroup3).",
+      "if": {
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "type": {
+            "const": "group"
+          }
+        }
+      },
+      "then": {
+        "$ref": "#/$defs/PlaceholderGroup3"
+      },
+      "else": {
+        "$ref": "#/$defs/GroupedPlaceholder"
+      }
+    },
+    "PlaceholderGroup3": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "placeholders"
+      ],
+      "description": "The innermost placeholder group (the third level): it holds regions only, never another group.",
+      "properties": {
+        "type": {
+          "const": "group",
+          "description": "Marks the entry as a placeholder group."
+        },
+        "composition": {
+          "$ref": "#/$defs/Composition",
+          "description": "How the group arranges its regions; see PlaceholderGroup.composition."
+        },
+        "placeholders": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/GroupedPlaceholder"
+          },
+          "description": "The group's regions, in reading order."
+        }
+      }
+    },
+    "GroupedPlaceholder": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type"
+      ],
+      "description": "A region inside a placeholder group: a body content kind only. Headings ('title', 'subtitle', 'tag') stay at the record's top level, and only a top-level image placeholder may carry a placement.",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "text",
+            "list",
+            "image",
+            "video",
+            "chart",
+            "table",
+            "code",
+            "metric",
+            "quote",
+            "timeline"
+          ],
+          "description": "The content kind of the region, from the one OPF content-kind vocabulary (see Placeholder.type)."
+        }
+      }
+    },
     "Placeholder": {
       "type": "object",
       "required": [
@@ -6553,7 +6727,7 @@ var layout = {
         },
         "placement": {
           "$ref": "#/$defs/ImagePlacement",
-          "description": "Image placeholders only. Bleeds the slide's image for this region to one slide edge, as an image block's placement does: the n-th image placeholder places the slide's n-th top-level image (Slide.image or an image block in blocks) unless that block sets its own placement. The headings and the other content compose in the rest of the slide."
+          "description": "Image placeholders only. Bleeds the slide's image for this region to one slide edge, as an image block's placement does: the n-th image placeholder (counting the image regions of placeholder groups too, in reading order) places the slide's n-th top-level image (Slide.image or an image block in blocks) unless that block sets its own placement. Only a top-level image placeholder may carry a placement; a region inside a placeholder group cannot bleed to a slide edge. The headings and the other content compose in the rest of the slide."
         }
       }
     },
@@ -6631,7 +6805,7 @@ var layout = {
             "left",
             "right"
           ],
-          "description": "Where the primary chart sits relative to the other body content. Composition applies it below the slide's and the deck's design.chartPrimary, with the semantics described there."
+          "description": "Where the primary chart sits relative to the other body content. Composition applies it below the slide's and the deck's design.chartPrimary, with the semantics described there. It is shorthand for a placeholder group: a record can state the same structure explicitly as a root row or column of the chart and one PlaceholderGroup of the other regions, weighted 3:2."
         },
         "imageFit": {
           "type": "string",
@@ -6655,7 +6829,7 @@ var layout = {
     "Composition": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Portable dynamic composition. Slide fields override the resolved layout. Nested groups arrange their children independently, inheriting only minFontSize and overflow. Explicit promoted regions retain their positions.",
+      "description": "Portable dynamic composition. Slide fields override the resolved layout. Nested groups (placeholder groups here, content groups in a slide) arrange their children independently, inheriting only minFontSize and overflow. Explicit promoted regions retain their positions.",
       "properties": {
         "mode": {
           "type": "string",