ggaction 0.0.24 → 0.0.26

package/src/actions/composition/adjacent.js

@@ -0,0 +1,90 @@
+import { adjacentLegendPresentation } from "../../materialization/compositionLegends.js";
+import { facetUnitTemplate } from "../facets/actions.js";
+import { compositionPlotBounds } from "../../materialization/composition.js";
+import { closedAction, getWrappedActionMetadata } from "../../core/action.js";
+import { validateOptionObject } from "../../core/validation.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { resolveAdjacentSource } from "../../materialization/adjacentSource.js";
+import { requireMaterializedDataset } from "../../selectors/datasets.js";
+import { findSemanticScale } from "../../selectors/scales.js";
+import { inheritTextMetrics } from "../textMetrics/index.js";
+import { resolveEffectiveThemeFrame } from "../theme/state.js";
+import { normalizeCompositionShares } from "../../core/compositionScales.js";
+import { hconcatAction, vconcatAction } from "./actions.js";
+
+import { plotComposition } from "../../selectors/plotComposition.js";
+import { inferCompositionOptions, constructorChannels } from "../../grammar/plotComposition.js";
+import { COMPOSITION_PLOT_ACTIONS } from "../../grammar/plotComposition.js";
+export const ADJACENT_PLOT_ACTIONS = COMPOSITION_PLOT_ACTIONS;
+
+const createAdjacentPlot = /* @__PURE__ */ closedAction({
+  op: "createAdjacentPlot", description: "Add a chart beside the current view with shared scales and aligned plots.", scope: "any"
+}, ["id", "source", "position", "plot", "share", "gap", "align", "legends"], function (args = {}) {
+  const grouped = this.compositionSpec && this.compositionSpec.type !== "facet";
+  const { view: sourceView, layer: source } = resolveAdjacentSource(this, args.source);
+  const template = sourceView.compositionSpec ? facetUnitTemplate(sourceView, true) : sourceView;
+  const position = args.position ?? "right";
+  if (!["left", "right", "top", "bottom"].includes(position)) throw new Error("Adjacent position must be left, right, top, or bottom.");
+  const horizontal = ["left", "right"].includes(position);
+  const share = { ...normalizeCompositionShares(args.share ?? { [horizontal ? "y" : "x"]: true }) };
+  const plot = args.plot ?? { action: "createLinePlot", options: {} };
+  validateOptionObject(plot, ["action", "options", "inherit"], "Adjacent plot");
+  const action = plot.action ?? "createLinePlot";
+  if (!ADJACENT_PLOT_ACTIONS.includes(action) || !getWrappedActionMetadata(this[action])) throw new Error(`Unknown adjacent plot action "${action}".`);
+  const id = args.id === undefined ? "adjacent" : validateUserId(args.id, "Adjacent view id");
+  const sourceId = grouped ? this.compositionSpec.id : source.id;
+  if (id === sourceId) throw new Error("Adjacent view id must differ from its source view id.");
+  const supplied = plot.options ?? {};
+  if (supplied === null || typeof supplied !== "object" || Array.isArray(supplied)) throw new TypeError("Adjacent plot options must be an object.");
+  if (Object.hasOwn(supplied, "id")) throw new Error("Adjacent plot id is owned by the adjacent view; use the top-level id.");
+  const meaning = plotComposition(template,source.id);
+  const dataset = requireMaterializedDataset(template, supplied.data ?? meaning.data);
+  const bounds = compositionPlotBounds(this);
+  const sourceBounds = compositionPlotBounds(sourceView);
+  const canvas = this.graphicSpec.objects.canvas.properties;
+  let child = new this.constructor().createCanvas({ plot: { width: grouped && horizontal ? sourceBounds.width : bounds.width,
+      height: grouped && !horizontal ? sourceBounds.height : bounds.height },
+    margin: template.materializationConfigs.canvas.margin, background: canvas.background });
+  const theme = resolveEffectiveThemeFrame(template.materializationConfigs.theme);
+  if (theme) child = child.applyTheme({ theme: { base: theme.name, tokens: theme.tokens } });
+  child = inheritTextMetrics(template, child);
+  // Keep source tables available for subsequent authoring. A summary used by
+  // this constructor must not erase unused input variables from its new view.
+  // These remain independent immutable snapshots, not cross-view dependencies.
+  for (const input of template.semanticSpec.datasets) {
+    if (input.id !== dataset.id && (input.source || !Array.isArray(input.values))) continue;
+    child = child.createData({ id: input.id, values: input.values });
+  }
+  const options = { ...inferCompositionOptions(meaning,action,supplied,plot.inherit), id, data:dataset.id };
+  const roles=constructorChannels(action,options,meaning);
+  if(args.share===undefined) {
+    for(const channel of Object.keys(share)) {
+      const from=meaning.channels[channel],to=roles[channel];
+      if(!from||!to||from.field!==to.field||JSON.stringify(from.measurement.operations)!==JSON.stringify(to.operations)||
+        (meaning.coordinate?.type??'cartesian')!=='cartesian') delete share[channel];
+    }
+  }
+  for(const channel of ['x','y','color']) {
+    const role=meaning.channels[channel],selected=options[channel];
+    if(!role || (channel!=='color'&&!share[channel]) || !selected || selected.field!==role.field)continue;
+    const scale=findSemanticScale(template,role.scale);
+    if(scale) { const {id:_scaleId,...definition}=scale; if(selected.scale?.palette!==undefined) delete definition.range; options[channel]={...selected,scale:{...definition,...selected.scale}}; }
+  }
+  child = child[action](options);
+  if (share.color) {
+    const presentation = adjacentLegendPresentation(sourceView, source.id, child);
+    if (presentation) child = child.editLegend(presentation);
+  }
+  const original = new this.constructor({ ...this, actionStack: [], actionSequence: this._actionSequence });
+  const parent = new this.constructor({ trace: this.trace, actionStack: this.actionStack, actionSequence: this._actionSequence });
+  const entries = [{ id: sourceId, program: original }, { id, program: child }];
+  if (["left", "top"].includes(position)) entries.reverse();
+  return (horizontal ? hconcatAction : vconcatAction).call(parent, {
+    programs: entries, align: args.align ?? "plot", ...(args.gap === undefined ? {} : { gap: args.gap }),
+    share, legends: args.legends === undefined ? "collect" : args.legends
+  });
+});
+
+export function registerAdjacentPlotActions(ProgramClass) {
+  ProgramClass.prototype.createAdjacentPlot = createAdjacentPlot;
+}

package/src/actions/composition/index.js

@@ -1 +1,11 @@
-export { registerCompositionActions } from "./actions.js";
+import { registerActionTargetDispatcher } from "../../core/action.js";
+import { dispatchActionTargets } from "./targets.js";
+import { registerCompositionActions as registerStructureActions } from "./actions.js";
+import { registerAdjacentPlotActions } from "./adjacent.js";
+import { registerLayerPlotActions } from "./layer.js";
+export function registerCompositionActions(ProgramClass) {
+  registerActionTargetDispatcher(ProgramClass, dispatchActionTargets);
+  registerStructureActions(ProgramClass);
+  registerAdjacentPlotActions(ProgramClass);
+  registerLayerPlotActions(ProgramClass);
+}

package/src/actions/composition/layer.js

@@ -0,0 +1,42 @@
+import { closedAction } from '../../core/action.js';
+import { planLayerPlot } from './layerPlan.js';
+import { findLayer } from '../../selectors/layers.js';
+import { plotComposition } from '../../selectors/plotComposition.js';
+
+const createLayerPlot = /* @__PURE__ */ closedAction({op:'createLayerPlot',description:'Layer a native chart over a compatible source using shared coordinates and scales.'},
+  ['id','source','plot','placement'],function(args={}) {
+    const plan=planLayerPlot(this,args);
+    let next=this;
+    for (const edit of plan.scaleEdits) next=next.editScale(edit);
+    next=next[plan.action](plan.options);
+    for (const [channel, scale] of Object.entries(plan.rebind)) {
+      const owner = plotComposition(next, plan.id);
+      const layer = findLayer(next, owner.owner);
+      const method = {x:'encodeX',y:'encodeY',theta:'encodeTheta',radius:'encodeR'}[channel];
+      const {field,fieldType} = layer.encoding[channel];
+      next = next[method]({target:owner.owner,field,fieldType,scale:{id:scale}});
+    }
+    if(plan.deferredColor) next=next[plan.action==='createRugPlot'?'encodeStroke':'encodeColor']({target:plan.id,...plan.deferredColor});
+    const owner=plotComposition(next,plan.id);
+    const existing=new Set(this.semanticSpec.layers.map(layer=>layer.id));
+    const added=new Set(next.semanticSpec.layers.filter(layer=>!existing.has(layer.id)).map(layer=>layer.id));
+    if(!owner.ownedMarks.every(id=>added.has(id))) throw new Error('A layer must own its new compound marks independently.');
+    // Preserve the native mark block as one unit. Concrete roots keep their
+    // relative order; guides and unrelated graphics retain their positions.
+    const reorder = order => {
+      const addedRoots=order.filter(id=>added.has(id));
+      if(!addedRoots.length) return order;
+      const rest=order.filter(id=>!added.has(id));
+      const anchors=rest.map((id,index)=>existing.has(id)?index:-1).filter(i=>i>=0);
+      const at=anchors.length?(plan.placement==='back'?anchors[0]:anchors.at(-1)+1):rest.length;
+      rest.splice(at,0,...addedRoots); return rest;
+    };
+    for (const [id, graphic] of Object.entries(next.graphicSpec.objects)) {
+      if (!graphic.children) continue;
+      const children = reorder(graphic.children);
+      if (children.some((child, index) => child !== graphic.children[index]))
+        next = next.editGraphics({ target:id, property:'children', value:children });
+    }
+    return next;
+  });
+export function registerLayerPlotActions(ProgramClass){ProgramClass.prototype.createLayerPlot=createLayerPlot;}

package/src/actions/composition/layerPlan.js

@@ -0,0 +1,176 @@
+import { isPlainObject } from '../../core/immutable.js';
+import { validateUserId } from '../../core/identifiers.js';
+import { validateOptionObject } from '../../core/validation.js';
+import { hasLayer } from '../../selectors/layers.js';
+import { requireMaterializedDataset } from '../../selectors/datasets.js';
+import { normalizeGroupFields, validatePathSeriesAppearance } from '../../grammar/pathSeries.js';
+import { deriveLineSeries, resolveLineBins } from '../../grammar/lineSeries.js';
+import { findSemanticScale } from '../../selectors/scales.js';
+import { plotComposition, measurementUnit } from '../../selectors/plotComposition.js';
+import { inferCompositionOptions, constructorChannels, PLOT_COMPOSITION_ROLES, fieldEncoding } from '../../grammar/plotComposition.js';
+
+const get=(object,path)=>path.split('.').reduce((o,k)=>o?.[k],object);
+function set(object,path,value) {
+  const parts=path.split('.'),last=parts.pop(); let node=object;
+  for(const key of parts) { node[key]={...fieldEncoding(node[key])}; node=node[key]; }
+  node[last]=value;
+}
+function bindScale(program, options, path, id) {
+  if(!id) throw new Error(`The source has no scale for ${path}.`);
+  const requested=get(options,path), stored=findSemanticScale(program,id);
+  if(requested?.id!==undefined && requested.id!==id) throw new Error(`${path} must reuse source scale "${id}".`);
+  for(const [key,value] of Object.entries(requested??{})) {
+    if(key==='id') continue;
+    // Explicit automatic limits are compatible with an automatic source. A
+    // shared resource must never be silently redefined by a new consumer.
+    if(JSON.stringify(value)!==JSON.stringify(key==='palette'?stored?.range?.palette:stored?.[key])) throw new Error(`${path}.${key} conflicts with the shared source scale. Edit that scale first.`);
+  }
+  set(options,path,{ ...stored, id });
+}
+export function planLayerPlot(program,args={}) {
+  if(program.compositionSpec) throw new Error('Select one chart view; use editFacetSource for a faceted chart.');
+  const id=validateUserId(args.id??'layer','Layer plot id');
+  if(hasLayer(program,id)||Object.values(program.markConfigs).some(c=>c.raincloudPlot?.id===id)) throw new Error(`Layer plot "${id}" already exists. Supply a unique id.`);
+  const placement=args.placement??'front';
+  if(!['front','back'].includes(placement)) throw new Error('Layer placement must be front or back.');
+  const spec=args.plot;
+  validateOptionObject(spec,['action','options','inherit'],'Layer plot');
+  if(!PLOT_COMPOSITION_ROLES[spec?.action]) throw new Error('Layer plot requires a supported native plot.action.');
+  const supplied=spec.options??{};
+  if(!isPlainObject(supplied)) throw new TypeError('Layer plot options must be an object.');
+  if(Object.hasOwn(supplied,'id')) throw new Error('Use the top-level layer id, not plot.options.id.');
+  const source=plotComposition(program,args.source), kind=PLOT_COMPOSITION_ROLES[spec.action];
+  if(args.source && args.source!==source.owner && program.markConfigs[source.owner]?.raincloudPlot?.id!==args.source) throw new Error('Layer source must be an independent plot owner, not one of its generated marks.');
+  const family=['polar','radial','radar'].includes(kind)?'polar':kind==='parallel'?'parallel':'cartesian';
+  if(source.coordinate?.type!==family) throw new Error(`Cannot overlay ${family} and ${source.coordinate?.type} coordinates. Add an adjacent chart instead.`);
+  if(supplied.coordinate!==undefined&&supplied.coordinate!==source.coordinate.id) throw new Error('Layer plots must reuse the source coordinate.');
+  const options=inferCompositionOptions(source,spec.action,supplied,spec.inherit);
+  if (['createLinePlot','createPolarLinePlot','createAreaPlot'].includes(spec.action)) {
+    // A point's per-row color does not necessarily describe one whole path.
+    // Reuse the native series contract before deciding whether omitted color
+    // can be inherited; explicit choices must still fail rather than disappear.
+    const color=options.color===undefined?undefined:{fieldType:'nominal',...fieldEncoding(options.color)};
+    const pathColor=color && {...color,scale:color.field===source.channels.color?.field?source.channels.color.scale:color.scale?.id};
+    const path={id,mark:{type:spec.action==='createAreaPlot'?'area':'line',missing:options.line?.missing??'error'},encoding:{...(pathColor?{color:pathColor}:{}),
+      ...(options.groupBy===undefined?{}:{group:{fieldType:'nominal',fields:normalizeGroupFields(options.groupBy)}})}};
+    const rows=requireMaterializedDataset(program,options.data).values;
+    const validate=()=>{
+      if (spec.action==='createAreaPlot' && path.encoding.color && !['nominal','ordinal'].includes(color.fieldType))
+        throw new Error('createAreaPlot color requires a categorical field.');
+      validatePathSeriesAppearance(rows,path,program.semanticSpec.scales);
+      if(path.mark.type==='line') {
+        for(const channel of ['x','y','theta','radius']) if(options[channel])
+          path.encoding[channel]={...fieldEncoding(options[channel]),scale:source.channels[channel]?.scale};
+        deriveLineSeries(rows,path,{scales:program.semanticSpec.scales,
+          xBinBoundaries:path.encoding.x?.bin===undefined?undefined:
+            resolveLineBins(rows,path,findSemanticScale(program,source.channels.x?.scale)).boundaries,
+          xDomain:program.resolvedScales[source.channels.x?.scale]?.domain,
+          yDomain:program.resolvedScales[source.channels.y?.scale]?.domain,
+          thetaDomain:program.resolvedScales[source.channels.theta?.scale]?.domain});
+      }
+    };
+    try {validate();} catch (error) {
+      if (supplied.color!==undefined || options.color===undefined) throw error;
+      delete options.color;
+      delete path.encoding.color;
+      validate();
+    }
+  }
+  if(spec.action==='createRegressionPlot' && ['x','y'].some(axis=>source.channels[axis]?.fieldType!=='quantitative')) throw new Error('Regression requires two quantitative source axes.');
+  if(spec.action==='createBarPlot' && ['x','y'].some(axis=>options[axis]?.aggregate) && !['x','y'].some(axis=>['nominal','ordinal'].includes(options[axis]?.fieldType)||options[axis]?.bin)) throw new Error('Bar layers require a categorical or binned position.');
+  if(kind==='heatmap' && ['x','y'].some(axis=>source.channels[axis]?.fieldType!=='quantitative')) throw new Error('A density heatmap layer requires two quantitative source axes.');
+  if(spec.action==='createDumbbellPlot') {
+    if(!fieldEncoding(options.start)?.field) throw new Error('Dumbbell requires an explicit start field; it cannot be inferred from one measure.');
+    if(fieldEncoding(options.start).field===fieldEncoding(options.end)?.field) throw new Error('Dumbbell start and end fields must be distinct.');
+  }
+  if(['summaryXY','categoryValue','density','endpoint'].includes(kind)&&options.color?.fieldType==='quantitative') throw new Error('A grouped distribution layer requires a categorical color field.');
+  if(['createStripPlot','createBeeswarmPlot'].includes(spec.action) && ['x','y'].filter(axis=>['nominal','ordinal'].includes(source.channels[axis]?.fieldType)).length!==1) throw new Error('Strip and Beeswarm require one categorical slot and one measure.');
+  if(kind==='rug') {
+    const axis=options.y?'y':'x';
+    if(!(axis==='y'?['left','right']:['top','bottom']).includes(options.edge)) throw new Error(`Rug ${axis} uses ${axis==='y'?'left or right':'top or bottom'} edges.`);
+    if(!['quantitative','temporal'].includes(options[axis]?.fieldType))throw new Error('Rug requires a quantitative or temporal axis.');
+  }
+  const category=options.category?.field ?? ['x','y'].map(axis=>options[axis]).find(e=>['nominal','ordinal'].includes(e?.fieldType))?.field;
+  if (options.color?.field && ['summaryXY','categoryValue'].includes(kind) && spec.action!=='createIntervalPlot' &&
+      options.color.field!==category && !(spec.action==='createViolinPlot'&&options.split?.field===options.color.field))
+    throw new Error('This summary color must name its category or an explicit supported split field.');
+  if (kind === 'rug' && spec.inherit?.color !== false && !options.color && source.channels.color?.field) {
+    options.color = { field: source.channels.color.field, fieldType: source.channels.color.fieldType };
+  }
+  let deferredColor;
+  if(['endpoint','rug'].includes(kind)&&options.color) {
+    if(kind==='endpoint' && options.color.field!==options.category.field) throw new Error('Endpoint summary color must be the category field.');
+    deferredColor=options.color; delete options.color;
+  }
+  if (spec.action==='createAreaPlot' && options.missing!=='break') {
+    const fields=options.groupBy===undefined?[]:normalizeGroupFields(options.groupBy);
+    const groups=new Map();
+    for (const row of requireMaterializedDataset(program,options.data).values) {
+      const key=JSON.stringify(fields.map(field=>row[field]));
+      groups.set(key,(groups.get(key)??0)+1);
+    }
+    if (!groups.size || [...groups.values()].some(count=>count<2))
+      throw new Error('Each area series requires at least two observations. Choose another layer or a less granular group.');
+  }
+  options.id=id; options.coordinate=source.coordinate.id;
+  // A layer consumes existing guides. createGuides can be called once after
+  // constructing the view; constructors must not duplicate or reset them.
+  if(options.guides!==undefined&&options.guides!==false) throw new Error('Layer guides are shared; call createGuides on the completed view.');
+  options.guides=false;
+  const rebind = {}, scaleEdits = [];
+  if(kind==='radial') {
+    if(!['count','sum'].includes(options.aggregate)||(options.aggregate==='sum')!==(options.value!==undefined)) throw new Error('Radial plots require count without a value field or sum with a value field.');
+    if(spec.action==='createPiePlot') {
+      const expected={aggregate:options.aggregate,...(options.aggregate==='sum'?{weight:options.value}:{})};
+      if(source.role!=='pie'||JSON.stringify(expected)!==JSON.stringify(source.channels.theta?.measurement.parameters)) throw new Error('Pie layers require the same angle partition, aggregate and weight.');
+    } else {
+      const mapping=spec.action==='createRosePlot'?'area':'radius-length';
+      if(findSemanticScale(program,source.channels.radius?.scale)?.radialMapping!==mapping) throw new Error('Radial layers require the same radius mapping (area or radius-length).');
+    }
+  }
+  if (['createViolinPlot','createRaincloudPlot','createBoxPlot','createGradientPlot','createBarPlot'].includes(spec.action)) {
+    for (const channel of ['x','y']) {
+      const role = source.channels[channel], scale = findSemanticScale(program,role?.scale);
+      if (scale?.type === 'point') scaleEdits.push({id:scale.id,type:'band',paddingInner:0,paddingOuter:0});
+    }
+  }
+  if(kind==='radar') {
+    const fields=source.channels.theta?.fields;
+    if(source.role!=='radar'||JSON.stringify(options.wide?.fields)!==JSON.stringify(fields)) throw new Error('Radar layers require identical dimensions and order.');
+    if(options.order&&JSON.stringify(options.order)!==JSON.stringify(fields)) throw new Error('Radar layers require the source dimension order.');
+    rebind.theta = source.channels.theta.scale;
+    rebind.radius = source.channels.radius.scale;
+  } else if(kind==='parallel') {
+    const dimensions=options.dimensions?.map(fieldEncoding);
+    if(!dimensions||JSON.stringify(dimensions.map(d=>d.field))!==JSON.stringify(source.dimensions?.map(d=>d.field))) throw new Error('Parallel layers require identical dimensions and order.');
+    options.dimensions=dimensions.map((d,index)=>{const o={...d};bindScale(program,{dimension:o},'dimension.scale',source.dimensions[index].scale);return {...o,scale:{id:source.dimensions[index].scale}};});
+  } else {
+    const channels=constructorChannels(spec.action,options,source);
+    if(!Object.keys(channels).length || (kind==='polar' && (!channels.theta || !channels.radius))) throw new Error('The source does not supply the required positional fields.');
+    for(const [channel,candidate] of Object.entries(channels)) {
+      const original=source.channels[channel];
+      if(!original||candidate.field!==original.field||candidate.fieldType!==original.fieldType||
+        measurementUnit(candidate.operations)!==original.measurement.unit||
+        (candidate.temporalUnit??null)!==(original.temporalUnit??null))
+        throw new Error(`Layer ${channel} must measure the same field, type, and units as the source. Use a follow overlay or an adjacent chart for different measurements.`);
+      if (kind === 'ecdf') rebind[channel] = original.scale;
+      else if (kind === 'horizon' && channel === 'y') set(options,candidate.path,{id:original.scale});
+      else {
+        bindScale(program,options,candidate.path,original.scale);
+        const promotion=scaleEdits.find(s=>s.id===original.scale);
+        if(promotion) { const bound={...get(options,candidate.path),...promotion}; delete bound.padding; set(options,candidate.path,bound); }
+      }
+    }
+    if(kind==='horizon'&&JSON.stringify(source.channels.y.measurement.parameters)!==JSON.stringify({bands:options.bands,baseline:options.baseline,extent:options.extent,resolve:options.resolve})) throw new Error('Horizon layers require the same folding parameters.');
+  }
+  if(spec.action==='createDumbbellPlot') bindScale(program,options,'start.scale',source.channels[options.orientation==='horizontal'?'x':'y'].scale);
+  if(kind==='radial') {
+    options.category.scale={id:source.channels.theta.scale};
+    if(options.radiusScale) options.radiusScale={id:source.channels.radius.scale};
+  }
+  if(kind==='heatmap') options.color={...(options.color??{}),scale:{...(options.color?.scale??{}),id:options.color?.scale?.id??`${id}Color`}};
+  else if(options.color?.field && options.color.field!==source.channels.color?.field) options.color={...options.color,scale:{...options.color.scale,id:options.color.scale?.id??`${id}Color`}};
+  if(options.color?.field && options.color.field===source.channels.color?.field) bindScale(program,options,'color.scale',source.channels.color.scale);
+  if(deferredColor?.field===source.channels.color?.field && deferredColor) deferredColor={...deferredColor,scale:{id:source.channels.color.scale}};
+  return {id,source,action:spec.action,options,placement,rebind,scaleEdits,deferredColor};
+}

package/src/actions/composition/targets.js

@@ -0,0 +1,105 @@
+import { getWrappedActionMetadata } from "../../core/action.js";
+import { restoreProgramContextKeys } from "../../core/programState.js";
+import { normalizeActionTargets } from "../../grammar/actionTargets.js";
+import { compositionLegends } from "../../materialization/compositionLegends.js";
+import { legendBlockChannels } from "../../grammar/legendBlocks.js";
+import { assertGuideCollisionBlocks } from "../../layout/guideCollisions.js";
+import { resolveGuideCollisionBlocks } from "../../materialization/guides/resources.js";
+
+function collectedLegends(program, path = [], result = new Map()) {
+  if (!program.compositionSpec || program.compositionSpec.facet) return result;
+  const legends = compositionLegends(program, program.children);
+  for (const legend of legends) for (const target of legend.targets) {
+    const child = atPath(program, target.childPath), key = JSON.stringify([...path, ...target.childPath]);
+    const kinds = result.get(key) ?? new Set();
+    for (const [kind, config] of Object.entries(child.guideConfigs.legend ?? {})) {
+      if ((target.id === undefined || config.target === target.id) && legendBlockChannels(kind, config).some(channel => legend.channels.includes(channel))) kinds.add(kind);
+    }
+    result.set(key, kinds);
+  }
+  for (const [id, child] of Object.entries(program.children)) collectedLegends(child, [...path,id], result);
+  return result;
+}
+
+function visibleGuideConfigs(program, hidden) {
+  return { ...program.guideConfigs, legend: Object.fromEntries(Object.entries(program.guideConfigs.legend ?? {})
+    .filter(([kind]) => !hidden?.has(kind))) };
+}
+
+// Internal planning frame: callers still replay one public scoped action on
+// the composition. The collected copies are not visible in this local frame.
+export function compositionTargetProgram(program, path) {
+  const selected = atPath(program, path), hidden = collectedLegends(program).get(JSON.stringify(path));
+  return hidden ? selected._withContext({ compositionCollectedLegends: [...hidden] }) : selected;
+}
+
+function atPath(program, path) {
+  for (const id of path) {
+    if (program.compositionSpec?.type === "facet") throw new Error("Facet cells follow their source; use editFacetSource for persistent edits.");
+    if (!Object.hasOwn(program.children, id)) throw new Error(`Unknown target child "${id}".`);
+    program = program.children[id];
+  }
+  return program;
+}
+
+function changePath(program, path, transform) {
+  if (!path.length) return transform(program);
+  const [id, ...rest] = path;
+  return program._withCompositionState({ compositionSpec: program.compositionSpec,
+    children: { ...program.children, [id]: changePath(program.children[id], rest, transform) } });
+}
+
+function refreshAncestors(original, revised) {
+  if (!revised.compositionSpec || original === revised) return revised;
+  let children = revised.children;
+  const changed = [];
+  for (const [id, child] of Object.entries(children)) {
+    if (child === original.children[id]) continue;
+    children = { ...children, [id]: original.children[id] ? refreshAncestors(original.children[id], child) : child };
+    changed.push(id);
+  }
+  if (!changed.length) return revised;
+  let next = revised._withCompositionState({ compositionSpec: revised.compositionSpec, children });
+  for (const id of changed) next = next.useProgram({ id });
+  return next.materializeComposition();
+}
+
+// Explicit public dispatch only. Edits run on immutable candidates, then shared
+// domains and all changed ancestor snapshots are materialized once from the
+// complete final state. This avoids intermediate mixed-palette/domain failures.
+export function dispatchActionTargets(program, wrappedAction, args) {
+  const targets = normalizeActionTargets(args.target);
+  for (const target of targets) {
+    const selected = atPath(program, target.childPath);
+    if (target.facetSource && selected.compositionSpec?.type !== "facet") throw new Error("facetSource requires a facet view.");
+    if (selected.compositionSpec?.type === "facet" && target.id !== undefined && !target.facetSource) {
+      throw new Error("Target a facet source through editFacetSource, or identify an explicit childPath.");
+    }
+  }
+  const { target: _target, ...options } = args;
+  const collected = collectedLegends(program);
+  let next = program;
+  for (const target of targets) next = changePath(next, target.childPath, selected => {
+    const hidden = collected.get(JSON.stringify(target.childPath));
+    const candidate = hidden ? selected._withContext({ compositionCollectedLegends: [...hidden] }) : selected;
+    const nativeOptions = { ...options, ...(target.id === undefined ? {} : { target: target.id }) };
+    const result = target.facetSource
+      ? candidate.editFacetSource({ action: { method: getWrappedActionMetadata(wrappedAction).op, options: nativeOptions } })
+      : wrappedAction.call(candidate, nativeOptions);
+    if (!hidden) return result;
+    return restoreProgramContextKeys(result, selected, ["compositionCollectedLegends"]);
+  });
+  const revised = refreshAncestors(program, next);
+  // The parent layout checks the collected graphic against retained content.
+  // Releasing sharing must also validate the newly visible local guides.
+  if (collected.size) {
+    const remaining = collectedLegends(revised);
+    for (const key of collected.keys()) {
+      const child = JSON.parse(key).reduce((node,id)=>node?.children?.[id],revised);
+      if (!child) continue;
+      assertGuideCollisionBlocks(resolveGuideCollisionBlocks(child.graphicSpec,
+        visibleGuideConfigs(child, remaining.get(key)), child.titleConfig, child.materializationConfigs.textMetrics));
+    }
+  }
+  return revised;
+}

package/src/actions/data/derived.js

@@ -1,3 +1,4 @@
+import { assertIndependentOverlayGeometry } from "../../grammar/overlay.js";
 import {resolveDatasetTransformInputs} from "./shared.js";
 import { closedAction } from "../../core/action.js";
 import { validateGraphicItemLimit } from "../../core/validation.js";
@@ -96,6 +97,7 @@ export const releaseDerivedData = /* @__PURE__ */ closedAction(
       "calculations", "datasets", validatedId
     ]);
     next = next._withoutMaterializationConfig(["regressionFits", validatedId]);
+    next = next._withoutMaterializationConfig(["rowProvenance", validatedId]);
     for (const owner of selfOwners) {
       const [, family, ownerId] = owner.path;
       next = next._withoutMaterializationConfig(["data", family, ownerId]);
@@ -136,6 +138,7 @@ export const rebindLayerData = /* @__PURE__ */ closedAction(
 );
 
 function assertIndependentMark(program, layer) {
+  assertIndependentOverlayGeometry(layer, "bindMarkData");
   const config = program.markConfigs[layer.id] ?? {};
   const role = OWNED_MARK_ROLES.find(key => config[key] !== undefined);
   if (role !== undefined) {

package/src/actions/data/filter.js

@@ -1 +1 @@
-import{findRaincloudParent as b}from"../../selectors/raincloud.js";import{filterRaincloud as T,materializeRaincloudFilter as B,removeRaincloudFilter as A}from"./raincloudFilter.js";import{closedAction as m}from"../../core/action.js";import{validateUserId as p}from"../../core/identifiers.js";import{withPreviewDatasetValues as z}from"../primitives/semanticAction.js";import{deriveFilteredRows as P,normalizeFilterTransform as L}from"../../grammar/filter.js";import{deriveMarkFilteredRows as N,markFilterSelectors as E,normalizeMarkFilterTransform as K}from"../../grammar/markFilter.js";import{resolveMarkFilterSelection as M}from"../../materialization/selection/filter.js";import{synchronizeBoxFilter as y}from"../boxPlots/components.js";import{findSelectionPolicy as q}from"../../materialization/selection/policies/index.js";import{applyLayerDataRematerialization as w,applyLayerEmptyDataView as $}from"../../materialization/dependencies.js";import{hasDataset as R,findDataset as O,resolveDatasetReference as V,requireLayer as h,resolveEligibleLayer as C}from"../../selectors/index.js";import{MATERIALIZE_OPTIONS as I,requireDerivedDataset as _}from"./shared.js";import{assertFieldsAvailable as H,deriveTransformSchema as J,transformInputFields as U}from"../../grammar/datasetSchema.js";const Y=Object.freeze(["id","source","field","oneOf","noneOf","predicate","range","nulls"]),x=Object.freeze(["grain","field","channel","property","op","value","values","min","max","inclusive","count","groupBy","ties"]),Z=Object.freeze(["target","mode",...x]),G=Object.freeze(["target"]),Q=Object.freeze(["id"]);function W(i,t){if(i.mark?.type!=="bar"||i.encoding?.x?.bin===void 0)return;const n=[...new Set(t.flatMap(e=>[e.channels.x,e.channels.x2]).filter(Number.isFinite))].sort((e,r)=>e-r);return n.length<2?void 0:n}const ke=m({op:"materializeFilteredData",description:"Materialize one filtered derived dataset."},I,function(i={}){const{id:t,source:n,transform:e}=_(this,i.id,"filter");H(n.schema,U(e),{data:n.id,operation:"materializeFilteredData"});const r=P(n.values,e),d=J(n.schema,e,r,{sourceId:n.id,ownerId:t});return this.editSemantic({property:`dataset[${t}].values`,value:r})}),ve=m({op:"filterData",description:"Create a named dataset from one field filter."},Y,function(i={}){const t=p(i.id,"Filtered dataset id"),n=p(i.source??this.context.currentData,"Source dataset id"),e=V(this,n,"Filter source dataset").id,r=L(i),d=this.createDerivedData({id:t,source:e,transform:[r]}).materializeFilteredData({id:t});return this.actionStack.length===1?d._withMaterializationConfig(["data","filter",t],{current:t}):d}),Fe=m({op:"materializeMarkFilteredData",description:"Materialize member rows retained by one final-item mark selection."},I,function(i={}){const{id:t,dataset:n,source:e,transform:r}=_(this,i.id,"markFilter"),d=b(this,r.target);if(d!==void 0)return B(this,{id:t,source:e,transform:r},d);const f=h(this,r.target);if(f?.data!==n.source)throw new Error(`Mark filter target "${r.target}" must still use source dataset "${n.source}".`);let s=this,c=e.values;const o=E(r);for(const[g,k]of o.entries()){const u=M(s,r.target,k);c=N(c,u.items,u.keys,f),g<o.length-1&&(s=z(s,{id:t,values:c,target:r.target}),s=y(s,r.target,t),s=c.length===0?$(s,r.target):w(s,r.target),c=O(s,t).values)}o.length>1&&(s=z(s,{id:t,omitValues:!0}));let a=s.editSemantic({property:`dataset[${t}].values`,value:c});return h(a,r.target).data!==t&&(a=a.editSemantic({property:`layer[${r.target}].data`,value:t})),a=a._withMarkConfig(r.target,{...a.markConfigs[r.target],markFilter:{...a.markConfigs[r.target].markFilter,empty:c.length===0}}),a=y(a,r.target,t),c.length===0?a.materializeEmptyMark({id:r.target}):w(a,r.target)}),be=m({op:"materializeEmptyMark",description:"Clear one active empty-filter mark without changing its domains."},Q,function(i={}){const t=p(i.id,"Empty mark id"),n=h(this,t),e=this.markConfigs[t]?.markFilter,r=O(this,n.data);if(e?.empty!==!0||r?.values?.length!==0)throw new Error(`Mark "${t}" does not own an active empty filter.`);return $(this,t)});function D(i,t){const n=i.markConfigs[t.id]?.markFilter,e=O(i,t.data),r=e?.transform?.[0];if(!(e?.source===void 0||r?.type!=="markFilter"||r.target!==t.id))return{dataset:e.id,source:e.source,selectors:E(r),...n?.originalBin===void 0?{}:{originalBin:n.originalBin}}}function X(i,t){const n=i.markConfigs[t]??{},{markFilter:e,...r}=n;return i._withMarkConfig(t,r)}function ee(i,t,n){let e=i;const r=t.encoding?.x?.bin??{};for(const d of["maxBins","step","boundaries"])Object.hasOwn(n,d)?e=e.editSemantic({property:`layer[${t.id}].encoding.x.bin.${d}`,value:n[d]}):Object.hasOwn(r,d)&&(e=e.editSemantic({property:`layer[${t.id}].encoding.x.bin.${d}`,remove:!0}));return e}function j(i,t,n){let e=y(i,t.id).editSemantic({property:`layer[${t.id}].data`,value:n.source});return n.originalBin!==void 0&&(e=ee(e,h(e,t.id),n.originalBin)),e=X(e,t.id).releaseDerivedData({id:n.dataset})._withContext({currentData:n.source}),w(e,t.id)}function te(i,t){const n=`${t}FilteredData`;if(!R(i,n))return n;let e=2;for(;R(i,`${n}${e}`);)e+=1;return`${n}${e}`}function re(i,t){return JSON.stringify(i)===JSON.stringify(t)}const Me=m({op:"removeMarkFilter",description:"Remove one active final-item filter and restore its source."},G,function(i={}){const t=i.target===void 0?void 0:p(i.target,"Mark filter target id"),n=b(this,t);if(n!==void 0)return A(this,n);const e=C(this,{target:t,label:"mark filter",predicate:r=>D(this,r)!==void 0});return j(this,e,D(this,e))}),ye=m({op:"filterMarks",description:"Retain selected final mark items through immutable derived data."},Z,function(i={}){if(i.mode!==void 0&&!["replace","compose"].includes(i.mode))throw new Error(`Unknown mark filter mode "${i.mode}".`);const t=i.target===void 0?void 0:p(i.target,"Filter mark target id"),n=b(this,t);if(n!==void 0){const l=Object.fromEntries(x.flatMap(F=>Object.hasOwn(i,F)?[[F,i[F]]]:[]));return T(this,i,n,l)}const e=C(this,{target:t,label:"filter mark",predicate:l=>l.data!==void 0&&q(l.mark?.type)!==void 0});if(this.markConfigs[e.id]?.itemFilterable===!1)throw new Error(`filterMarks does not support composite mark "${e.id}"; filter its source dataset first.`);const r=D(this,e),d=Object.fromEntries(x.flatMap(l=>Object.hasOwn(i,l)?[[l,i[l]]]:[])),f=M(this,e.id,d),s=r?.selectors.at(-1);if(s!==void 0&&re(s,f.selector))return this;if(r!==void 0&&i.mode===void 0)throw new Error('Repeated filterMarks requires mode "replace" or "compose".');const c=r===void 0||i.mode==="replace"?[f.selector]:[...r.selectors,f.selector];let o=r===void 0?this:j(this,e,r);const a=h(o,e.id),g=M(o,e.id,c[0]),k=K(e.id,c),u=W(a,g.items),S=a.mark?.type==="bar"&&a.encoding?.x?.bin!==void 0?a.encoding.x.bin:void 0,v=te(o,e.id);if(o=o.createDerivedData({id:v,source:a.data,transform:[k]}),u!==void 0){for(const l of["maxBins","step"])Object.hasOwn(a.encoding.x.bin,l)&&(o=o.editSemantic({property:`layer[${a.id}].encoding.x.bin.${l}`,remove:!0}));o=o.editSemantic({property:`layer[${a.id}].encoding.x.bin.boundaries`,value:u})}return o=o._withMarkConfig(a.id,{...o.markConfigs[a.id],markFilter:{dataset:v,source:a.data,selectors:c,empty:!1,...S===void 0?{}:{originalBin:S}}}),o.materializeMarkFilteredData({id:v})});export{ve as filterData,ye as filterMarks,be as materializeEmptyMark,ke as materializeFilteredData,Fe as materializeMarkFilteredData,Me as removeMarkFilter};
+import{isSourceOwnedText as j}from"../../grammar/text.js";import{markFilterSourceIndices as B}from"../../materialization/selection/rows.js";import{assertIndependentOverlayGeometry as P}from"../../grammar/overlay.js";import{findRaincloudParent as M}from"../../selectors/raincloud.js";import{filterRaincloud as A,materializeRaincloudFilter as L,removeRaincloudFilter as N}from"./raincloudFilter.js";import{closedAction as m}from"../../core/action.js";import{validateUserId as p}from"../../core/identifiers.js";import{withPreviewDatasetValues as z}from"../primitives/semanticAction.js";import{deriveFilteredRows as K,normalizeFilterTransform as q}from"../../grammar/filter.js";import{deriveMarkFilteredRows as V,markFilterSelectors as E,normalizeMarkFilterTransform as H}from"../../grammar/markFilter.js";import{resolveMarkFilterSelection as b}from"../../materialization/selection/filter.js";import{synchronizeBoxFilter as y}from"../boxPlots/components.js";import{findSelectionPolicy as J}from"../../materialization/selection/policies/index.js";import{applyLayerDataRematerialization as w,applyLayerEmptyDataView as $}from"../../materialization/dependencies.js";import{hasDataset as R,findDataset as O,resolveDatasetReference as U,requireLayer as h,resolveEligibleLayer as C}from"../../selectors/index.js";import{MATERIALIZE_OPTIONS as I,requireDerivedDataset as _}from"./shared.js";import{assertFieldsAvailable as Y,deriveTransformSchema as G,transformInputFields as Z}from"../../grammar/datasetSchema.js";const Q=Object.freeze(["id","source","field","oneOf","noneOf","predicate","range","nulls"]),x=Object.freeze(["rows","grain","field","channel","property","op","value","values","min","max","inclusive","count","groupBy","ties"]),W=Object.freeze(["target","mode",...x]),X=Object.freeze(["target"]),ee=Object.freeze(["id"]);function te(i,t){if(i.mark?.type!=="bar"||i.encoding?.x?.bin===void 0)return;const n=[...new Set(t.flatMap(e=>[e.channels.x,e.channels.x2]).filter(Number.isFinite))].sort((e,r)=>e-r);return n.length<2?void 0:n}const we=m({op:"materializeFilteredData",description:"Materialize one filtered derived dataset."},I,function(i={}){const{id:t,source:n,transform:e}=_(this,i.id,"filter");Y(n.schema,Z(e),{data:n.id,operation:"materializeFilteredData"});const r=K(n.values,e),d=G(n.schema,e,r,{sourceId:n.id,ownerId:t});return this.editSemantic({property:`dataset[${t}].values`,value:r})}),Oe=m({op:"filterData",description:"Create a named dataset from one field filter."},Q,function(i={}){const t=p(i.id,"Filtered dataset id"),n=p(i.source??this.context.currentData,"Source dataset id"),e=U(this,n,"Filter source dataset").id,r=q(i),d=this.createDerivedData({id:t,source:e,transform:[r]}).materializeFilteredData({id:t});return this.actionStack.length===1?d._withMaterializationConfig(["data","filter",t],{current:t}):d}),xe=m({op:"materializeMarkFilteredData",description:"Materialize member rows retained by one final-item mark selection."},I,function(i={}){const{id:t,dataset:n,source:e,transform:r}=_(this,i.id,"markFilter"),d=M(this,r.target);if(d!==void 0)return L(this,{id:t,source:e,transform:r},d);const f=h(this,r.target);if(f?.data!==n.source)throw new Error(`Mark filter target "${r.target}" must still use source dataset "${n.source}".`);let s=this,c=e.values;const o=E(r);for(const[g,k]of o.entries()){const u=b(s,r.target,k);c=V(c,u.items,u.keys,f),g<o.length-1&&(s=z(s,{id:t,values:c,target:r.target}),s=y(s,r.target,t),s=c.length===0?$(s,r.target):w(s,r.target),c=O(s,t).values)}o.length>1&&(s=z(s,{id:t,omitValues:!0}));let a=s.editSemantic({property:`dataset[${t}].values`,value:c})._withMaterializationConfig(["rowProvenance",t],{indices:B(e.values,c)});return h(a,r.target).data!==t&&(a=a.editSemantic({property:`layer[${r.target}].data`,value:t})),a=a._withMarkConfig(r.target,{...a.markConfigs[r.target],markFilter:{...a.markConfigs[r.target].markFilter,empty:c.length===0}}),a=y(a,r.target,t),c.length===0?a.materializeEmptyMark({id:r.target}):w(a,r.target)}),Se=m({op:"materializeEmptyMark",description:"Clear one active empty-filter mark without changing its domains."},ee,function(i={}){const t=p(i.id,"Empty mark id"),n=h(this,t),e=this.markConfigs[t]?.markFilter,r=O(this,n.data);if(e?.empty!==!0||r?.values?.length!==0)throw new Error(`Mark "${t}" does not own an active empty filter.`);return $(this,t)});function S(i,t){const n=i.markConfigs[t.id]?.markFilter,e=O(i,t.data),r=e?.transform?.[0];if(!(e?.source===void 0||r?.type!=="markFilter"||r.target!==t.id))return{dataset:e.id,source:e.source,selectors:E(r),...n?.originalBin===void 0?{}:{originalBin:n.originalBin}}}function re(i,t){const n=i.markConfigs[t]??{},{markFilter:e,...r}=n;return i._withMarkConfig(t,r)}function ie(i,t,n){let e=i;const r=t.encoding?.x?.bin??{};for(const d of["maxBins","step","boundaries"])Object.hasOwn(n,d)?e=e.editSemantic({property:`layer[${t.id}].encoding.x.bin.${d}`,value:n[d]}):Object.hasOwn(r,d)&&(e=e.editSemantic({property:`layer[${t.id}].encoding.x.bin.${d}`,remove:!0}));return e}function T(i,t,n){let e=y(i,t.id).editSemantic({property:`layer[${t.id}].data`,value:n.source});return n.originalBin!==void 0&&(e=ie(e,h(e,t.id),n.originalBin)),e=re(e,t.id).releaseDerivedData({id:n.dataset})._withContext({currentData:n.source}),w(e,t.id)}function ne(i,t){const n=`${t}FilteredData`;if(!R(i,n))return n;let e=2;for(;R(i,`${n}${e}`);)e+=1;return`${n}${e}`}function ae(i,t){return JSON.stringify(i)===JSON.stringify(t)}const De=m({op:"removeMarkFilter",description:"Remove one active final-item filter and restore its source."},X,function(i={}){const t=i.target===void 0?void 0:p(i.target,"Mark filter target id"),n=M(this,t);if(n!==void 0)return N(this,n);const e=C(this,{target:t,label:"mark filter",predicate:r=>S(this,r)!==void 0});return T(this,e,S(this,e))}),ze=m({op:"filterMarks",description:"Retain selected final mark items through immutable derived data."},W,function(i={}){if(i.mode!==void 0&&!["replace","compose"].includes(i.mode))throw new Error(`Unknown mark filter mode "${i.mode}".`);const t=i.target===void 0?void 0:p(i.target,"Filter mark target id"),n=M(this,t);if(n!==void 0){const l=Object.fromEntries(x.flatMap(F=>Object.hasOwn(i,F)?[[F,i[F]]]:[]));return A(this,i,n,l)}const e=C(this,{target:t,label:"filter mark",predicate:l=>l.data!==void 0&&(t!==void 0||!j(l))&&J(l.mark?.type)!==void 0});if(P(e,"filterMarks"),this.markConfigs[e.id]?.itemFilterable===!1)throw new Error(`filterMarks does not support composite mark "${e.id}"; filter its source dataset first.`);const r=S(this,e),d=Object.fromEntries(x.flatMap(l=>Object.hasOwn(i,l)?[[l,i[l]]]:[])),f=b(this,e.id,d),s=r?.selectors.at(-1);if(s!==void 0&&ae(s,f.selector))return this;if(r!==void 0&&i.mode===void 0)throw new Error('Repeated filterMarks requires mode "replace" or "compose".');const c=r===void 0||i.mode==="replace"?[f.selector]:[...r.selectors,f.selector];let o=r===void 0?this:T(this,e,r);const a=h(o,e.id),g=b(o,e.id,c[0]),k=H(e.id,c),u=te(a,g.items),D=a.mark?.type==="bar"&&a.encoding?.x?.bin!==void 0?a.encoding.x.bin:void 0,v=ne(o,e.id);if(o=o.createDerivedData({id:v,source:a.data,transform:[k]}),u!==void 0){for(const l of["maxBins","step"])Object.hasOwn(a.encoding.x.bin,l)&&(o=o.editSemantic({property:`layer[${a.id}].encoding.x.bin.${l}`,remove:!0}));o=o.editSemantic({property:`layer[${a.id}].encoding.x.bin.boundaries`,value:u})}return o=o._withMarkConfig(a.id,{...o.markConfigs[a.id],markFilter:{dataset:v,source:a.data,selectors:c,empty:!1,...D===void 0?{}:{originalBin:D}}}),o.materializeMarkFilteredData({id:v})});export{Oe as filterData,ze as filterMarks,Se as materializeEmptyMark,we as materializeFilteredData,xe as materializeMarkFilteredData,De as removeMarkFilter};

package/src/actions/data/raincloudFilter.js

@@ -1,4 +1,5 @@
 import { findDataset, hasDataset } from "../../selectors/datasets.js";
+import { markFilterSourceIndices } from "../../materialization/selection/rows.js";
 import { findRaincloudParent } from "../../selectors/raincloud.js";
 import { normalizeMarkSelector, selectMarkItemKeys } from "../../grammar/markSelection.js";
 import { deriveMarkFilteredRows, normalizeMarkFilterTransform } from "../../grammar/markFilter.js";
@@ -18,7 +19,8 @@ export function deriveRaincloudFilteredRows(values, selectors) {
 
 export function materializeRaincloudFilter(program, { id, source, transform }, owner) {
   const values = deriveRaincloudFilteredRows(source.values, transform.selectors);
-  let next = program.editSemantic({ property: `dataset[${id}].values`, value: values });
+  let next = program.editSemantic({ property: `dataset[${id}].values`, value: values })
+    ._withMaterializationConfig(["rowProvenance", id], { indices: markFilterSourceIndices(source.values, values) });
   next = next.editRaincloudPlot({ target: owner.id, data: id });
   const revised = findRaincloudParent(next, owner.id);
   return next._withMarkConfig(revised.ownerId, {

package/src/actions/encodings/appearance.js

@@ -1,8 +1,10 @@
+import { validatePointShape } from "../../grammar/pointShapes.js";
 import { APPEARANCE_MARK_TYPES } from "../../core/vocabulary.js";
 import { removeEncoding } from "./remove.js";
 import { canMaterializeBar } from "../../materialization/marks/index.js";
 import { action } from "../../core/action.js";
 import { validatePathSeriesAppearance } from "../../grammar/pathSeries.js";
+import { validatePathGroupAppearance } from "../../materialization/marks/grouping.js";
 import { assertEncodingSelectionCompatibility } from "../../materialization/selection/compatibility.js";
 import {
   readScaleField,
@@ -179,9 +181,24 @@ const encodeSize = /* @__PURE__ */ action(
 const encodeShape = /* @__PURE__ */ action(
   {
     op: "encodeShape",
-    description: "Encode a nominal field as point shape."
+    description: "Assign constant or field-driven point shape."
   },
   function (args = {}) {
+    validateOptions(args, [...FIELD_OPTIONS, "value"], "encodeShape");
+    const hasValue = Object.hasOwn(args, "value");
+    if (hasValue === Object.hasOwn(args, "field")) {
+      throw new Error("encodeShape requires exactly one of value or field.");
+    }
+    if (hasValue) {
+      if (args.fieldType !== undefined || args.scale !== undefined) {
+        throw new Error("Constant shape does not accept fieldType or scale.");
+      }
+      const shape = validatePointShape(args.value);
+      const { id: target, layer } = resolveTarget(this, args.target, APPEARANCE_MARK_TYPES.encodeShape, "point mark");
+      const next = layer.encoding?.shape === undefined ? this
+        : removeEncoding.call(this, { target, channel: "shape" });
+      return next.editPointMark({ target, shape });
+    }
     return encodeAppearanceField(this, "shape", args, "encodeShape");
   }
 );
@@ -231,7 +248,7 @@ const encodeOpacity = /* @__PURE__ */ action(
       this,
       args.target,
       APPEARANCE_MARK_TYPES.encodeOpacity,
-      "point, rule, line, bar or rect mark"
+      "point, rule, line, area, bar or rect mark"
     );
     if (hasValue) {
       validateOpacityValue(args.value, "encodeOpacity");
@@ -244,7 +261,7 @@ const encodeOpacity = /* @__PURE__ */ action(
         .clearOpacityEncoding({ target })
         ._withoutMaterializationConfig(["marks", target, "opacity"])
         ._withMarkConfig(target, { ...config, opacity: args.value });
-      if (["line", "rect"].includes(layer.mark.type)) {
+      if (["line", "area", "rect"].includes(layer.mark.type)) {
         return rematerializeEncoding(next, target, "opacity", undefined, layer);
       }
       if (layer.mark.type === "bar") {
@@ -268,13 +285,15 @@ const encodeOpacity = /* @__PURE__ */ action(
       args.scale ?? {}
     );
     const scale = resolveOpacityScaleDefinition(this, requestedScale);
-    if (["line", "rect"].includes(layer.mark.type)) {
+    if (["line", "area", "rect"].includes(layer.mark.type)) {
       if (Object.hasOwn(scale, "unknown")) {
-        throw new Error("Line and Rect opacity do not support unknown fallback.");
+        throw new Error("Line, Area and Rect opacity do not support unknown fallback.");
       }
-      validatePathSeriesAppearance(dataset.values, {
+      const prospective = {
         ...layer, encoding: { ...layer.encoding, opacity: { field: args.field, fieldType } }
-      }, this.semanticSpec.scales);
+      };
+      if (layer.mark.type === "area") validatePathGroupAppearance(this, prospective, dataset);
+      else validatePathSeriesAppearance(dataset.values, prospective, this.semanticSpec.scales);
     }
     readScaleField(dataset.values, args.field, fieldType, {
       allowUnknown: Object.hasOwn(scale, "unknown")

package/src/actions/encodings/channels.js

@@ -61,6 +61,7 @@ const CHANNEL_METHODS = Object.freeze({
 const FORBIDDEN_PAYLOAD_KEYS = Object.freeze(["target", "coordinate", "id"]);
 
 const DEFERRED_MARK_OPERATIONS = Object.freeze([
+  "rematerializeOverlay",
   "materializeEmptyMark",
   "rematerializePointMark",
   "rematerializeTickMark",