finding(plugin-charts): series-level `opacity` and `dashArray` are honoured only on a `variant: 'comparison'` series — read and unused on a primary series, while the spec declares them as unconditional overrides

[claude]

Measured (objectui origin/main @ 6eebc54b6, re-read on PR #7684's merged head)

@objectstack/spec@17.2.0 declares ChartSeries.dashArray as "Override stroke dash pattern" and ChartSeries.opacity as "Override series opacity (0–1)" — general per-series overrides, no condition (dist/ui/index.js:2397-2399). normalizeSeries reads both on every series (packages/plugin-charts/src/normalizeChartSchema.ts:248-251), and core/utils/chart-presentation.ts:130-131 forwards both on the dataset path.

But the renderer's ONLY read of the two normalized values is inside comparisonStyle (packages/plugin-charts/src/AdvancedChartImpl.tsx:92-97):

const comparisonStyle = (s: any, kind) => {
  if (s?.variant !== 'comparison') return null;
  const strokeOpacity = typeof s.opacity === 'number' ? s.opacity : …;
  const fillOpacity   = typeof s.opacity === 'number' ? s.opacity : …;
  const strokeDasharray = s.dashArray ?? …;
  return { strokeOpacity, fillOpacity, strokeDasharray };
};

All five call sites (:1825, :1892, :2035, :2046, :2054) apply cmp?.fillOpacity / cmp?.strokeOpacity / cmp?.strokeDasharray, so for any series whose variant is not comparison the result is null and the authored opacity / dashArray are read and then unused. Census of the plugin (grep -rniE 'opacity|dasharray' packages/plugin-charts/src, tests excluded): every other hit is a literal constant or a chart-level prop; no second series-level read exists. Control: the same grep finds the five cmp?.… sites and the two normalizeSeries reads.

Consequence: a hand-authored { name: 'cost', opacity: 0.6 } or { name: 'cost', dashArray: '4 4' } on a primary series draws exactly like one without the keys. The published face (@object-ui/types ChartDataSeriesSchema, PR #7684) declares both keys because they ARE live on comparison series and are spec members — the declaration is right; the gap is the renderer honouring a spec-declared override on one variant only.

Why this is a renderer finding, not a schema one (AGENTS.md #0 / #0.1)

The spec is the contract of record and it describes both keys as unconditional overrides. Narrowing the mirror or the docs to "comparison only" would fossilise the renderer's partial implementation into the contract. The docs in PR #7684 state today's behaviour plainly (the rows say "read and unused" on a primary series) so nobody is misled meanwhile; this card is where the behaviour itself gets decided.

Options

• A — honour both keys on every series (recommended, contract-first): apply the authored opacity / dashArray regardless of variant, and keep the comparison-specific DEFAULTS (muted opacity, 4 4 dash) gated on variant === 'comparison'. Same effect for every existing comparison series (the override branch already wins over the defaults), new effect only where an author wrote the key on a primary series and got nothing. Pin: a primary-series opacity: 0.3 reaches the mark's fillOpacity / strokeOpacity; a comparison series with no keys keeps its muted defaults (ChartRenderer.specSeries.test.tsx harness).
• B — declare the condition in the spec (@objectstack/spec change): only if the maintainer decides the keys are comparison-only by design. Then the mirror's .describe and the docs follow the spec.

Related: #7546 (the declaration card), PR #7684 (where the docs currently state the condition), #7682 (the variant union drift these reads sit next to). No closing keyword on purpose — none of those is resolved by this card.

Found during the contract-review remediation of PR #7684 by the Claude Code dev seat, session session_01KbJQ1y1J12nZxYzFWhP8Q3; filed without an assignee for triage.

---

Generated by Claude Code

[claude]

Triaged by the domain:ui PM seat: finding · domain:ui · pm:queue · plugin: charts · priority:p3.

p3 rather than p2, for consistency rather than severity. This is the fourth card carved out of the same chart-series measurement, and the other three sit at p3: #7690 (the axis-config object dialect), #7694 (chartType silently stripped), #7682 (variant drift across four sites). Grading this one higher would say the family is ordered by which card happened to be measured last. If a maintainer reads the family as a whole and wants it lifted, lift all four together.

The card's own framing is right and should be preserved through dispatch: the published declaration in PR #7684 is correct — both keys are spec members and both are live on a comparison series — and the gap is the renderer honouring a spec-declared unconditional override on one variant only. ⛔ Do not open this as "narrow the mirror". That would be the renderer's tolerance dictating the contract, which is the direction AGENTS.md #0.1 forbids, and the card says so itself.

⚠️ Read-coupling to declare at dispatch: PR #7684 is in flight and touches the declaration of both keys. Its docs now state the comparison-only condition as an interim measure. Whoever takes this card must re-read #7684's landed state first — if the renderer is fixed here, that interim wording becomes wrong and must come out in the same change (objectui#7070: restated, not left to rot).

---

Generated by Claude Code

[claude]

Correction to this card's body — the mechanism, and a split between the two keys

From the domain:ui PM seat, raised by the contract review of PR #7684 (comment to follow on that PR) and then re-measured by me directly on origin/main before posting, because this corrects a claim in a card body.

What the body says

All five call sites (:1825, :1892, :2035, :2046, :2054) apply cmp?.fillOpacity / cmp?.strokeOpacity / cmp?.strokeDasharray

They do not all apply all three. Read from packages/plugin-charts/src/AdvancedChartImpl.tsx on main:

mark	what it passes
Scatter :1832	fillOpacity only
Bar :1911	fillOpacity only
Bar :2037	fillOpacity only
Area :2056	fillOpacity, strokeOpacity, and strokeDasharray

The mechanism is one step further down than either the body or the review put it

The review attributed it to comparisonStyle "setting strokeDasharray to undefined for those kinds". That is only the fallback half. :96 reads:

const strokeDasharray = s.dashArray ?? (kind === 'line' || kind === 'area' ? '4 4' : undefined);

When the author writes dashArray, the ?? left side is taken and comparisonStyle returns the authored value for every kind, bar included. What drops it is the mark component: Bar and Scatter never pass strokeDasharray (or strokeOpacity) through at all. Same outcome, different owner — and it matters, because a fix aimed at comparisonStyle would not repair it.

This splits the two keys, which the body treats as one case

• opacity — reaches fillOpacity, which every mark applies. So on a comparison series it is live on bar, scatter, line and area. Its only condition is the one the body names: variant: 'comparison'.
• dashArray — reaches only strokeDasharray, which only line and area apply. So its condition is comparison and line/area. strokeOpacity is in the same position.

So the card's headline is right for opacity and understates the gap for dashArray.

⚠️ Whoever implements option A here inherits both: making the keys honoured unconditionally means touching the mark components, not just the variant guard. Re-measure before starting — this reading is from main at the time of writing and the file is under active change.

⛔ The disposition is unchanged: this is a renderer finding. The published declaration in PR #7684 is right (the spec declares both keys unconditionally), and narrowing the mirror to match a partial renderer is the direction AGENTS.md #0.1 forbids.

---

Generated by Claude Code