ggaction 0.0.24 → 0.0.26

package/src/materialization/composition.js

@@ -1,4 +1,12 @@
-import { freezeOwned } from "../core/immutable.js";
+import { resolveConcreteGraphicBounds, resolveGraphicParentOffset } from "../grammar/schemas/graphicBounds.js";
+import { layoutCompositionLegends } from "../layout/compositionLegend.js";
+import { compositionLegends } from "./compositionLegends.js";
+import { translateGraphic } from "./graphicTranslation.js";
+import { compositionTitleLayout, materializeCompositionTitle } from "./compositionTitle.js";
+import { resolveGraphicBounds } from "../layout/canvas.js";
+import { resolveSharedCompositionChildren } from "./compositionScales.js";
+import { resolvePlacedPlotBounds } from "../layout/composition.js";
+import { cloneAndFreeze, freezeOwned } from "../core/immutable.js";
 import {
   requireSingleOrderedGraphicByType
 } from "../grammar/schemas/graphicTree.js";
@@ -6,7 +14,7 @@ import {
   resolveCompositionLayout,
   resolveCompositionSnapshotPlacement
 } from "../layout/composition.js";
-import { namespaceGraphicSnapshot } from "./compositionSnapshot.js";
+import { namespaceGraphicSnapshot, namespaceGraphicId } from "./compositionSnapshot.js";
 
 const ZERO_MARGIN = freezeOwned({ top: 0, right: 0, bottom: 0, left: 0 });
 
@@ -34,16 +42,117 @@ export function compositionChildDescriptor(id, program) {
   };
 }
 
-export function resolveCompositionProgramLayout(program) {
-  program._assertCompositionProgram("resolveCompositionProgramLayout");
+export function compositionPlotBounds(program) {
+  if (!program.compositionSpec) return resolveGraphicBounds(program);
+  if (program.compositionSpec.type === "facet") {
+    // The retained facet already owns concrete child placements, including
+    // header/legend reservations. Read those snapshots without re-entering its
+    // materializer (which uses the shared snapshot attachment helpers below).
+    const placements = program.compositionSpec.children.map(id => {
+      const { id: canvas } = requireSingleOrderedGraphicByType(program.children[id].graphicSpec, "canvas");
+      const root = program.graphicSpec.objects[namespaceGraphicId(`${program.compositionSpec.id}-${id}`, canvas)];
+      if (!root) throw new Error("Plot alignment requires a materialized facet view.");
+      return { id, x: root.properties.x, y: root.properties.y, width: root.properties.width, height: root.properties.height };
+    });
+    return resolvePlacedPlotBounds({ placements, plots: program.compositionSpec.children.map(id =>
+      ({ id, ...resolveGraphicBounds(program.children[id]) })) });
+  }
+  const { children, layout } = prepareCompositionSnapshots(program);
+  return resolvePlacedPlotBounds({ placements: layout.children,
+    plots: layout.children.map(({ id }) => ({ id, ...compositionPlotBounds(children[id]) })) });
+}
+
+function resizeCompositionPlotExtent(program, dimension, size) {
+  const current = compositionPlotBounds(program);
+  if (Math.abs(current[dimension] - size) < 1e-6) return program;
+  if (!program.compositionSpec) return program.editCanvas({ plot: {
+    width: current.width, height: current.height, [dimension]: size } });
   const spec = program.compositionSpec;
-  return resolveCompositionLayout({
-    direction: spec.direction,
-    children: spec.children.map(id => compositionChildDescriptor(id, program.children[id])),
-    gap: spec.gap,
-    align: spec.align,
-    padding: spec.padding
-  });
+  const delta = size - current[dimension];
+  if (spec.type === "facet") {
+    const plots = Object.values(program.children).map(resolveGraphicBounds);
+    if (!plots.length || plots.some(plot => plot.width !== plots[0].width || plot.height !== plots[0].height)) {
+      throw new Error("Plot-aligned facets require uniform source plot sizes.");
+    }
+    const tracks = dimension === "width" ? spec.columns : Math.ceil(spec.children.length / spec.columns);
+    return program.editFacetSource({ action: { method: "editCanvas", options: { plot: {
+      width: plots[0].width, height: plots[0].height, [dimension]: plots[0][dimension] + delta / tracks } } } });
+  }
+  const parallel = (dimension === "width") === (spec.direction === "horizontal");
+  const increment = parallel ? delta / spec.children.length : delta;
+  const children = Object.fromEntries(spec.children.map(id => [id,
+    resizeCompositionPlotExtent(program.children[id], dimension, compositionPlotBounds(program.children[id])[dimension] + increment)]));
+  return program._withCompositionState({ compositionSpec: spec, children }).materializeComposition();
+}
+
+const snapshotCache = new WeakMap();
+
+// Measure the visible snapshots that remain after guide collection. Canvas
+// margins and the removed legend's old lane are not occupied chart content.
+function retainedCompositionBounds(program, children, layout, legend) {
+  const removed = new Set(legend.flatMap(block => block.remove)), bounds = [];
+  for (const cell of layout.children) {
+    const child = resizeChildForSnapshot(children[cell.id], cell);
+    const placement = resolveSnapshotPlacement(child, cell, layout);
+    const namespace = `${program.compositionSpec.id}-${cell.id}`;
+    const visit = id => {
+      if (removed.has(namespaceGraphicId(namespace, id))) return;
+      const object = child.graphicSpec.objects[id];
+      if (object.type === "canvas") {
+        for (const nested of object.children ?? []) visit(nested);
+      } else {
+        const value = resolveConcreteGraphicBounds(child.graphicSpec, id, child.materializationConfigs.textMetrics);
+        if (value) bounds.push({ left: value.left + placement.x, right: value.right + placement.x,
+          top: value.top + placement.y, bottom: value.bottom + placement.y });
+      }
+    };
+    for (const id of child.graphicSpec.order) visit(id);
+  }
+  return bounds;
+}
+
+export function prepareCompositionSnapshots(program) {
+  program._assertCompositionProgram("prepareCompositionSnapshots");
+  const spec = program.compositionSpec;
+  let bySpec = snapshotCache.get(program.children);
+  const cached = bySpec?.get(spec);
+  if (cached && cached.titleConfig === program.titleConfig && cached.semanticTitle === program.semanticSpec.title) return cached;
+  let children = resolveSharedCompositionChildren(program.children, spec.share);
+  if (spec.align === "plot") {
+    const dimension = spec.direction === "horizontal" ? "height" : "width";
+    const plots = Object.fromEntries(spec.children.map(id => [id, compositionPlotBounds(children[id])]));
+    const size = Math.max(...Object.values(plots).map(plot => plot[dimension]));
+    children = Object.fromEntries(spec.children.map(id => {
+      const child = children[id];
+      if (Math.abs(plots[id][dimension] - size) < 1e-6) return [id, child];
+      return [id, resizeCompositionPlotExtent(child, dimension, size)];
+    }));
+  }
+  const title = compositionTitleLayout(program);
+  const padding = { top: 0, bottom: 0, left: 0, right: 0, ...spec.padding };
+  if (title.config) padding[title.config.position] += title.reservation + 8;
+  const baseLayout = resolveCompositionLayout({ direction: spec.direction,
+    children: spec.children.map(id => ({ ...compositionChildDescriptor(id, children[id]),
+      ...(spec.align === "plot" ? { plot: compositionPlotBounds(children[id]) } : {}) })),
+    gap: spec.gap, align: spec.align, padding });
+  const legends = compositionLegends(program, children);
+  // Ordinary Canvas compositions also accept low-level graphical programs
+  // with no semantic plot margins. Only collected, plot-anchored guides need
+  // this data-region measurement; start/center/end layout uses child Canvases.
+  const plot = legends.length ? resolvePlacedPlotBounds({ placements: baseLayout.children,
+    plots: baseLayout.children.map(({ id }) => ({ id, ...compositionPlotBounds(children[id]) })) }) : undefined;
+  const retained = legends.length ? retainedCompositionBounds(program, children, baseLayout, legends) : [];
+  const { layout, frames: legendFrames } = layoutCompositionLegends(baseLayout, plot, legends, title, retained);
+  const dx = layout.children[0].x - baseLayout.children[0].x, dy = layout.children[0].y - baseLayout.children[0].y;
+  const retainedBounds = retained.map(b => ({ left: b.left + dx, right: b.right + dx, top: b.top + dy, bottom: b.bottom + dy }));
+  const result = { children, layout, title, legends, legendFrames, retainedBounds, titleConfig: program.titleConfig, semanticTitle: program.semanticSpec.title };
+  if (!bySpec) { bySpec = new WeakMap(); snapshotCache.set(program.children, bySpec); }
+  bySpec.set(spec, result);
+  return result;
+}
+
+export function resolveCompositionProgramLayout(program) {
+  return prepareCompositionSnapshots(program).layout;
 }
 
 function resizeChildForSnapshot(program, placement) {
@@ -65,7 +174,7 @@ function resizeChildForSnapshot(program, placement) {
 }
 
 function resolveSnapshotPlacement(program, placement, layout) {
-  if (program.compositionSpec === undefined) return placement;
+  if (program.compositionSpec === undefined || layout.align === "plot") return placement;
   const canvas = requireSingleOrderedGraphicByType(program.graphicSpec, "canvas");
   return resolveCompositionSnapshotPlacement({
     direction: layout.direction,
@@ -76,54 +185,38 @@ function resolveSnapshotPlacement(program, placement, layout) {
   });
 }
 
-function itemDefinitions(object) {
-  return object.items.map(item => ({
-    type: item.type ?? object.type,
-    properties: item.properties
-  }));
-}
-
 export function attachSnapshotObject(program, snapshot, id, parent) {
-  const object = snapshot.objects[id];
-  let next = program.createGraphics({
-    id,
-    type: object.type,
-    parent,
-    ...(object.items !== undefined && object.type !== "collection"
-      ? { length: object.items.length }
-      : {})
-  });
-  for (const [property, value] of Object.entries(object.properties ?? {})) {
-    next = next.editGraphics({ target: id, property, value });
-  }
-  if (object.items !== undefined) {
-    next = next.editGraphics({
-      target: id,
-      property: "items",
-      value: itemDefinitions(object)
-    });
-  }
-  if (object.clip !== undefined) next = next.editGraphics({target: id, property: "clip", value: object.clip});
-  for (const childId of object.children ?? []) {
-    next = attachSnapshotObject(next, snapshot, childId, id);
-  }
-  return next;
+  // Snapshot input is already materialized by the child domain actions. The
+  // enclosing materializeComposition/facet action owns this concrete transfer;
+  // there is no second semantic compilation or per-property authoring replay.
+  const objects = { ...program.graphicSpec.objects };
+  const attach = key => {
+    if (objects[key] !== undefined) throw new Error(`Graphic "${key}" already exists in the receiving snapshot.`);
+    const object = snapshot.objects[key];
+    if (!object) throw new Error(`Unknown snapshot graphic "${key}".`);
+    objects[key] = cloneAndFreeze(object);
+    for (const child of object.children ?? []) attach(child);
+  };
+  attach(id);
+  const owner = objects[parent];
+  if (!owner || !["canvas", "collection"].includes(owner.type)) throw new Error("Snapshot attachment requires a Canvas or collection parent.");
+  objects[parent] = freezeOwned({ ...owner, children: freezeOwned([...(owner.children ?? []), id]) });
+  return program._clone({ graphicSpec: freezeOwned({ ...program.graphicSpec, objects: freezeOwned(objects) }) });
 }
 
 export function clearCompositionChildren(program) {
   const canvas = program.graphicSpec.objects.canvas;
-  let next = program;
-  for (const id of canvas?.children ?? []) {
-    next = next.editGraphics({ target: id, remove: true });
-  }
-  return next;
+  return canvas?.children?.length ? program.editGraphics({ target: canvas.children, remove: true }) : program;
 }
 
 export function materializeCompositionGraphics(program) {
   program._assertCompositionProgram("materializeCompositionGraphics");
-  const layout = resolveCompositionProgramLayout(program);
-  const background = program.graphicSpec.objects.canvas?.properties
-    ?.background ?? "white";
+  const { layout, children, title, legends, legendFrames } = prepareCompositionSnapshots(program);
+  // A uniform child surface also covers parent gaps and reserved guide lanes.
+  // Mixed local backgrounds retain the composition's existing outer surface.
+  const backgrounds = new Set(Object.values(children).map(child => child.graphicSpec.objects.canvas?.properties.background));
+  const background = backgrounds.size === 1 && !backgrounds.has(undefined)
+    ? [...backgrounds][0] : program.graphicSpec.objects.canvas?.properties.background ?? "white";
   let next = clearCompositionChildren(program);
   if (next.graphicSpec.objects.canvas === undefined) {
     next = next.createGraphics({ id: "canvas", type: "canvas" });
@@ -137,7 +230,7 @@ export function materializeCompositionGraphics(program) {
   }
 
   for (const placement of layout.children) {
-    const source = program.children[placement.id];
+    const source = children[placement.id];
     const child = resizeChildForSnapshot(source, placement);
     const snapshotPlacement = resolveSnapshotPlacement(child, placement, layout);
     const snapshot = namespaceGraphicSnapshot(child.graphicSpec, {
@@ -148,6 +241,26 @@ export function materializeCompositionGraphics(program) {
     next = attachSnapshotObject(next, snapshot, snapshot.order[0], "canvas");
   }
 
+  for (const legend of legends) {
+    for (const id of legend.remove) if (next.graphicSpec.objects[id]) next = next.editGraphics({ target: id, remove: true });
+    const { source, roots, bounds, id } = legend;
+    next = next.createGraphics({ id, type: "canvas", parent: "canvas" });
+    for (const [property, value] of Object.entries({ ...legendFrames.get(id), background: "transparent" })) {
+      next = next.editGraphics({ target: id, property, value });
+    }
+    const snapshot = namespaceGraphicSnapshot(source.graphicSpec, { namespace: id });
+    for (const root of roots) {
+      const key = namespaceGraphicId(id, root);
+      next = attachSnapshotObject(next, snapshot, key, id);
+      const [parentX, parentY] = resolveGraphicParentOffset(source.graphicSpec, root);
+      next = translateGraphic(next, key, parentX - bounds.left, parentY - bounds.top);
+    }
+  }
+  if (title.config) {
+    const plot = resolvePlacedPlotBounds({ placements: layout.children,
+      plots: layout.children.map(({ id }) => ({ id, ...compositionPlotBounds(children[id]) })) });
+    next = materializeCompositionTitle(next, plot, title);
+  }
   return next._withCanvasConfig({
     margin: ZERO_MARGIN,
     size: { width: "auto", height: "auto" }

package/src/materialization/compositionLegends.js

@@ -0,0 +1,120 @@
+import { describeLegendBlock, legendBlockChannels } from "../grammar/legendBlocks.js";
+import { allLegendGraphicIds } from "./guides/resources.js";
+import { unionConcreteGraphicBounds } from "../grammar/schemas/graphicBounds.js";
+import { namespaceGraphicId } from "./compositionSnapshot.js";
+import { localLegendPlacement } from "../grammar/legendGroups.js";
+import { mapScaleConsumerValues } from "./scales/map.js";
+import { restoreLegendItemsOffset } from "./legendItemsOffset.js";
+
+// A categorical color/shape block can explain a color-only view too. Compare
+// encoded mappings, not labels or resource IDs. Constant glyphs in another
+// view do not establish a conflicting shape encoding.
+function coversLegend(candidate, other) {
+  if (candidate.channels.length === 1 && other.channels.length === 1) return true;
+  if (candidate.block.family !== "categorical" || other.block.family !== "categorical" ||
+      candidate.config.field !== other.config.field ||
+      other.channels.some(channel => !candidate.channels.includes(channel))) return false;
+  const values = other.config.domain;
+  if (!Array.isArray(values) || values.some(value => !candidate.config.domain.includes(value))) return false;
+  return other.channels.every(channel => {
+    const scaleFor = item => item.mappingSource.resolvedScales[item.config.scales[item.config.channels.indexOf(channel)]];
+    const a = scaleFor(candidate), b = scaleFor(other);
+    if (!a || !b || values.some(value => !a.domain.includes(value) || !b.domain.includes(value))) return false;
+    return JSON.stringify(mapScaleConsumerValues(values, a, channel)) ===
+      JSON.stringify(mapScaleConsumerValues(values, b, channel));
+  });
+}
+
+const visibleBlocks = new WeakMap();
+function collect(child) {
+  if (visibleBlocks.has(child)) return visibleBlocks.get(child);
+  const candidates = [];
+  if (child.compositionSpec && !child.compositionSpec.facet) {
+    for (const id of child.compositionSpec.children) {
+      for (const candidate of collect(child.children[id])) {
+        const remove = candidate.remove.map(root => namespaceGraphicId(`${child.compositionSpec.id}-${id}`, root));
+        // A nested composition may already have promoted this block. Its
+        // canonical leaves still contain it, but its rendered snapshot does not.
+        if (remove.every(root => child.graphicSpec.objects[root])) candidates.push({ ...candidate, remove,
+          targets: candidate.targets.map(target => ({ ...target, childPath: [id, ...target.childPath] })) });
+      }
+    }
+    for (const representative of compositionLegends(child, child.children)) {
+      const id = representative.id;
+      if (child.graphicSpec.objects[id]) {
+        const bounds = unionConcreteGraphicBounds(child.graphicSpec, [id], child.materializationConfigs.textMetrics);
+        const dx = bounds.left - representative.bounds.left, dy = bounds.top - representative.bounds.top;
+        const anchor = representative.anchorBounds ?? representative.bounds;
+        candidates.push({ ...representative, source: child,
+          roots: child.graphicSpec.objects[id].children ?? [id], remove: [id], bounds,
+          anchorBounds: { left: anchor.left + dx, right: anchor.right + dx, top: anchor.top + dy, bottom: anchor.bottom + dy } });
+      }
+    }
+  } else {
+    const intrinsic = restoreLegendItemsOffset(child);
+    for (const [kind, config] of Object.entries(child.guideConfigs.legend ?? {})) {
+      const channels = legendBlockChannels(kind, config);
+      const roots = allLegendGraphicIds([kind]).filter(id => child.graphicSpec.objects[id]);
+      const bounds = unionConcreteGraphicBounds(child.graphicSpec, roots, child.materializationConfigs.textMetrics);
+      if (!bounds) continue;
+      const local = localLegendPlacement(config);
+      const group = child.guideConfigs.legendGroups?.[config.target];
+      candidates.push({ source: child, mappingSource: child, roots, bounds,
+        anchorBounds: unionConcreteGraphicBounds(intrinsic.graphicSpec, roots, child.materializationConfigs.textMetrics), channels, config,
+        targets: [{ childPath: [], ...(child.compositionSpec?.facet ? {} : { id: config.target }) }],
+        block: describeLegendBlock(child, kind, config),
+        placement: { ...(local ?? group?.placement ??
+          { position: config.position, align: config.align, offset: config.offset }),
+          inferredOffset: local?.inferredOffset ?? group?.inferredOffset ?? config.inferredOffset }, remove: roots });
+    }
+  }
+  visibleBlocks.set(child, candidates);
+  return candidates;
+}
+
+// Scale compatibility is validated before this plan. Canonical child guides
+// remain intact; only the composed graphic snapshots are collected.
+export function compositionLegends(program, children = program.children) {
+  const candidates = program.compositionSpec.children.flatMap(id => collect(children[id]).map(candidate => ({
+    ...candidate, remove: candidate.remove.map(root => namespaceGraphicId(`${program.compositionSpec.id}-${id}`, root)),
+    targets: candidate.targets.map(target => ({ ...target, childPath: [id, ...target.childPath] }))
+  })));
+  const plans = [];
+  const removed = new Set();
+  if (program.compositionSpec.share?.color) {
+    const colors = candidates.filter(candidate => candidate.channels.includes("color"));
+    const ordered = [...colors].sort((a, b) => b.channels.length - a.channels.length);
+    const representative = ordered.find(candidate => colors.every(other => coversLegend(candidate, other)))
+      ?? colors.find(candidate => candidate.channels.length === 1);
+    if (representative) {
+      const collected = colors.filter(candidate => coversLegend(representative, candidate));
+      collected.forEach(candidate => removed.add(candidate));
+      plans.push({ ...representative, id: `${program.compositionSpec.id}-shared-color-legend`,
+        remove: collected.flatMap(candidate => candidate.remove),
+        targets: collected.flatMap(candidate => candidate.targets) });
+    }
+  }
+  for (const candidate of candidates) if (program.compositionSpec.legends === "collect" && !removed.has(candidate)) plans.push({ ...candidate,
+    // Derive identity from the canonical owner, never the current stack index.
+    id: namespaceGraphicId(JSON.stringify([program.compositionSpec.id, candidate.targets, candidate.channels]), "legend") });
+  return plans;
+}
+
+// New neighbours keep the existing shared guide's authored presentation. Scale
+// mappings and symbol semantics still belong to each native constructor.
+export function adjacentLegendPresentation(source, target, child) {
+  const from = collect(source).find(candidate => candidate.config.target === target && candidate.channels.includes("color"));
+  const to = collect(child).find(candidate => candidate.channels.includes("color"));
+  if (!from || !to) return undefined;
+  const config = from.config, options = { ...from.placement };
+  if (from.placement.inferredOffset ?? config.inferredOffset) delete options.offset;
+  delete options.inferredOffset;
+  for (const key of ["labels", "titleStyle", "titlePosition", "border", "itemsOffset"]) if (config[key] !== undefined) options[key] = config[key];
+  if (!config.inferredTitle) options.title = config.titleVisible === false ? false : config.title;
+  if (from.block.family === to.block.family) {
+    const presentation = from.block.family === "gradient" ? ["direction", "gradient"] : ["direction", "columns", "itemGap"];
+    for (const key of presentation) if (config[key] !== undefined) options[key] = config[key];
+    if (config.symbol && config.inferredSymbol === false) options.symbol = config.symbol;
+  }
+  return { target: to.config.target, channel: "color", ...options };
+}

package/src/materialization/compositionScales.js

@@ -0,0 +1,125 @@
+import { normalizeCompositionShares } from "../core/compositionScales.js";
+import { findSemanticScale } from "../selectors/scales.js";
+import { ownership } from "../selectors/markOwners.js";
+import { findCoordinate } from "../selectors/coordinates.js";
+import { hasOrdinalDomain } from "../grammar/scales/types.js";
+import { compositionChannel } from "../selectors/plotComposition.js";
+
+// A facet retains an unpartitioned source recipe at its root. Its resolved
+// source scale is not a displayed scale: aggregation/stacking is recomputed in
+// each cell. Read the actual cell domains, including independent facet scales.
+function displayedDomains(program, id) {
+  if (program.compositionSpec?.type === "facet") {
+    return program.compositionSpec.children.flatMap(child => displayedDomains(program.children[child], id));
+  }
+  return program.resolvedScales[id] ? [program.resolvedScales[id].domain] : [];
+}
+
+function mergeDomains(scale, domains, channel) {
+  if (hasOrdinalDomain(scale.type)) return [...new Set(domains.flat())];
+  if (scale.type === "quantile") return domains.flat().toSorted((a, b) => a - b);
+  if (!domains.length || domains.some(domain => domain.length !== 2 || domain.some(value => !Number.isFinite(value)))) {
+    throw new Error(`Shared ${channel} requires finite domains or compatible ordinal categories.`);
+  }
+  return [Math.min(...domains.flat()), Math.max(...domains.flat())];
+}
+
+function bindings(program, channel, path = []) {
+  if (program.compositionSpec && program.compositionSpec.type !== "facet") return Object.entries(program.children).flatMap(([id, child]) => bindings(child, channel, [...path, id]));
+  const owners = ownership(program);
+  const entries = new Map();
+  for (const layer of program.semanticSpec.layers) {
+    if (owners.has(layer.id) || layer.derivedBindings?.overlay || program.markConfigs[layer.id]?.statisticalReference) continue;
+    const encoding = layer.encoding?.[channel];
+    if (!encoding?.scale) continue;
+    // A constant anchor has no data-field meaning. Its private scale (for
+    // example an annotation's 0..1 plot coordinates) is not a shared data axis.
+    const role = compositionChannel(program, encoding, layer.data);
+    if (!role) continue;
+    if (["x", "y"].includes(channel) && findCoordinate(program, layer.coordinate)?.type !== "cartesian") {
+      throw new Error(`Shared ${channel} requires Cartesian positions.`);
+    }
+    const scale = findSemanticScale(program, encoding.scale);
+    if (!scale || !program.resolvedScales[scale.id]) throw new Error(`Shared ${channel} requires a materialized scale.`);
+    const meaning = { field: role.field, fields: role.fields, fieldType: role.fieldType,
+      aggregateUnit: role.measurement.unit === "sum" ? "value" : role.measurement.unit, temporalUnit: role.temporalUnit };
+    const previous = entries.get(scale.id);
+    if (previous && JSON.stringify(previous.meaning) !== JSON.stringify(meaning)) {
+      throw new Error(`Shared ${channel} has ambiguous field meaning inside a view.`);
+    }
+    entries.set(scale.id, { path, program, scale, meaning,
+      domain: mergeDomains(scale, displayedDomains(program, scale.id), channel) });
+  }
+  if (!entries.size) throw new Error(`Shared ${channel} is not encoded in view "${path.join("/") || "root"}".`);
+  return [...entries.values()];
+}
+
+function compatibleDefinition(scale, channel) {
+  const omitted = new Set(["id", "domain", "emptyDomain", "nice", "zero"]);
+  if (["x", "y"].includes(channel)) omitted.add("range");
+  return Object.fromEntries(Object.entries(scale).filter(([key]) => !omitted.has(key)).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function unionDomain(entries, channel) {
+  const first = entries[0];
+  const meaning = JSON.stringify(first.meaning);
+  const definition = JSON.stringify(compatibleDefinition(first.scale, channel));
+  for (const entry of entries) {
+    if (JSON.stringify(entry.meaning) !== meaning || JSON.stringify(compatibleDefinition(entry.scale, channel)) !== definition) {
+      throw new Error(`Cannot share ${channel}: field meaning and scale mapping must be compatible across views.`);
+    }
+  }
+  const explicit = entries.filter(entry => Array.isArray(entry.scale.domain)).map(entry => entry.scale.domain);
+  if (explicit.some(domain => JSON.stringify(domain) !== JSON.stringify(explicit[0]))) {
+    throw new Error(`Cannot share ${channel}: explicit domains conflict.`);
+  }
+  // An explicit common domain is intentional. Otherwise derive a fresh union on
+  // each composition edit; never feed yesterday's union back into inference.
+  if (explicit.length) return explicit[0];
+  return mergeDomains(first.scale, entries.map(entry => entry.domain), channel);
+}
+
+function updatePath(program, path, callback) {
+  if (!path.length) return callback(program);
+  const [id, ...rest] = path;
+  const children = { ...program.children, [id]: updatePath(program.children[id], rest, callback) };
+  return program._withCompositionState({ compositionSpec: program.compositionSpec, children });
+}
+
+function materializeChangedAncestors(original, revised) {
+  if (original === revised || !revised.compositionSpec || revised.compositionSpec.type === "facet") return revised;
+  const children = Object.fromEntries(Object.entries(revised.children).map(([id, child]) =>
+    [id, materializeChangedAncestors(original.children[id], child)]));
+  return revised._withCompositionState({ compositionSpec: revised.compositionSpec, children }).materializeComposition();
+}
+
+// Canonical children retain authored domains. Only render snapshots receive a
+// shared resolved domain, just as concat's automatic sizing derives snapshots.
+export function resolveSharedCompositionChildren(children, requested) {
+  const share = normalizeCompositionShares(requested);
+  const plans = [];
+  for (const [channel, enabled] of Object.entries(share)) {
+    if (!enabled) continue;
+    const entries = Object.entries(children).flatMap(([id, child]) => bindings(child, channel, [id]));
+    const domain = unionDomain(entries, channel);
+    for (const entry of entries) plans.push({ ...entry, domain });
+  }
+  let result = children;
+  const seen = new Map();
+  for (const { path: [id, ...path], scale, domain } of plans) {
+    const key = JSON.stringify([id, path, scale.id]);
+    if (seen.has(key)) {
+      if (JSON.stringify(seen.get(key)) !== JSON.stringify(domain)) throw new Error("Shared channels require incompatible domains on the same scale.");
+      continue;
+    }
+    seen.set(key, domain);
+    result = { ...result, [id]: updatePath(result[id], path, child => {
+      if (JSON.stringify(child.resolvedScales[scale.id]?.domain) === JSON.stringify(domain) &&
+          displayedDomains(child, scale.id).every(value => JSON.stringify(value) === JSON.stringify(domain))) return child;
+      return child.compositionSpec?.type === "facet"
+        ? child.editFacetSource({ action: { method: "editScale", options: { id: scale.id, domain } } })
+        : child.editScale({ id: scale.id, domain });
+    }) };
+  }
+  return Object.fromEntries(Object.entries(result).map(([id, child]) => [id, materializeChangedAncestors(children[id], child)]));
+}

package/src/materialization/compositionTitle.js

@@ -0,0 +1,96 @@
+import { textBoundsFitCanvas } from "../core/textMetrics.js";
+import { resolveConcreteGraphicBounds } from "../grammar/schemas/graphicBounds.js";
+import { alignedTextAnchor, alignedTitleAnchor, buildTitleReadingBlock, paintedTitleComponent, resolveTitleComponentBounds, titleTextProperties } from "../layout/title.js";
+const TITLE_IDS = ["chartTitle", "chartSubtitle"];
+export function compositionTitleLayout(program) {
+  if (program.semanticSpec.title.text === undefined) {
+    return { height: 0 };
+  }
+  const config = program.titleConfig;
+  if (config === undefined) {
+    throw new Error("Composition title requires chart title configuration.");
+  }
+  const block = buildTitleReadingBlock({
+    text: program.semanticSpec.title.text,
+    subtitle: program.semanticSpec.title.subtitle
+  }, config, program.materializationConfigs.textMetrics);
+  const top = 8 + config.offset;
+  if (top < 0) {
+    throw new Error("Composition title offset places text outside the Canvas.");
+  }
+  const reservation = Math.ceil(top + block.height);
+  return { config, block, top, reservation, height: config.position === "top" ? reservation : 0 };
+}
+
+function materializeTitleComponent(program, id, lines, centers, style, plot, title) {
+  if (lines.length === 0) return program;
+  const { config, block, top } = title;
+  const canvas = program.graphicSpec.objects.canvas.properties;
+  const horizontal = ["top", "bottom"].includes(config.position);
+  const component = paintedTitleComponent(horizontal ? {
+    x: alignedTextAnchor(plot.x, plot.width, config.align) + (config.alongOffset ?? 0),
+    y: centers.map(center => (config.position === "top" ? top : canvas.height - top - block.height) + center),
+    lines, textAlign: config.align,
+    ...(config.position === "bottom" ? { rotation: 0, explicitRotation: true } : {})
+  } : {
+    x: centers.map(center => config.position === "left" ? top + center : canvas.width - top - center),
+    y: alignedTitleAnchor(plot.y, plot.height, block.width, config.align) + (config.alongOffset ?? 0),
+    lines, textAlign: "center", rotation: config.position === "left" ? -Math.PI / 2 : Math.PI / 2,
+    explicitRotation: true
+  });
+  const bounds = resolveTitleComponentBounds(component, style, program.materializationConfigs.textMetrics);
+  if (!textBoundsFitCanvas(bounds, program.graphicSpec.objects.canvas.properties)) {
+    throw new Error("Composition title places text outside the Canvas.");
+  }
+  const count = component.lines.length;
+  let next = program.createGraphics({
+    id,
+    type: "text",
+    ...(count > 1 ? { length: count } : {}),
+    parent: "canvas"
+  });
+  for (const [property, value] of Object.entries({ ...titleTextProperties(component, style),
+    ...(component.explicitRotation ? { rotation: component.rotation } : {})
+  })) {
+    next = next.editGraphics({ target: id, property, value });
+  }
+  return next;
+}
+
+export function materializeCompositionTitle(program, plot, title) {
+  if (title.config.position === "top" && program.compositionSpec.topLane !== "shared") {
+    // Child Canvas margins already reserve space above visible chart content.
+    // Anchor against the retained ink instead of adding that empty space to
+    // the title gap. Keep child placements, authored margins and the explicit
+    // shared top-lane contract intact.
+    let edge = plot.y;
+    for (const [id, object] of Object.entries(program.graphicSpec.objects)) {
+      if (TITLE_IDS.includes(id) || object.type === "canvas" || object.children?.length ||
+          object.properties?.opacity === 0) continue;
+      const bounds = resolveConcreteGraphicBounds(program.graphicSpec, id, program.materializationConfigs.textMetrics);
+      if (bounds) edge = Math.min(edge, bounds.top);
+    }
+    title = { ...title, top: Math.max(title.top, edge - 16 - title.block.height) };
+  }
+  let next = materializeTitleComponent(
+    program,
+    TITLE_IDS[0],
+    title.block.titleLines,
+    title.block.titleCenters,
+    title.config.titleStyle,
+    plot,
+    title
+  );
+  if (title.block.subtitleLines.length > 0) {
+    next = materializeTitleComponent(
+      next,
+      TITLE_IDS[1],
+      title.block.subtitleLines,
+      title.block.subtitleCenters,
+      title.config.subtitleStyle,
+      plot,
+      title
+    );
+  }
+  return next;
+}