fix(engine): gate theme-derived colors on isOpaqueColor, not the literal 'transparent'

Three sites decided "is this background really a color?" by comparing
against the string 'transparent', which misses 'none' and alpha-zero
rgba() -- the exact truthy-but-invisible values the export-canvas fix
(529ebb8) already hardened against. All three now share core's existing
isOpaqueColor():

- charts/scatter/compute.ts: the default point stroke fell through to
  the raw background string, so a theme background of 'none' became
  stroke='none'. SVG drops the separator halo; canvas is worse, since an
  invalid strokeStyle assignment is silently ignored and the previous
  color keeps painting.
- theme/resolve.ts isDarkBackground(): a non-opaque background parsed to
  luminance 0 and was treated as dark, inverting chrome text on an
  effectively transparent (likely light) host. The existing comment
  already stated the intent -- no intrinsic luminance -- for the
  'transparent' literal; now it holds for every non-opaque value.
- theme/dark-mode.ts adaptTheme(): same equality check, same widening.
  No behavior change here (unparseable inputs already fell into the
  alreadyDark branch via luminance 0); this is convergence on one
  definition of transparency.

Also documents the rc.19 stroke-default change in migrating-v8.md
(section 20). It shipped in 644e0f8, whose non-conventional message
("bug: fix") kept it out of every generated changelog.

Author: rileyhilliard

docs/migrating-v8.md

@@ -907,6 +907,32 @@ escape hatch here. Charts rendering points on canvas get a much higher default
 
 ---
 
+## 20. Scatter point stroke follows the theme background
+
+Scatter and bubble points used to draw a white separator stroke unconditionally.
+The white halo is what gives overlapping dots separation on a light ground, but
+on a dark canvas it reads as a bright grid of rings. The default stroke now
+matches the resolved theme background when that background is an opaque color:
+
+```
+before:  stroke = mark.stroke ?? '#ffffff'
+after:   stroke = mark.stroke ?? (opaque theme background ? background : '#ffffff')
+```
+
+**What changes:** scatter charts on themes with an opaque dark background get
+dark separator strokes instead of white ones. The default theme background is
+`'transparent'`, so charts without a custom theme are unaffected, as is any
+theme whose background does not parse to an opaque color (`'none'`, alpha
+`rgba()`).
+
+**If you want the white halo back** on a dark theme, set it explicitly:
+
+```js
+{ mark: { type: 'point', stroke: '#ffffff' } }
+```
+
+---
+
 ## Verification
 
 After applying the changes above, run a build and check the console output.
@@ -928,3 +954,6 @@ warning at compile time with the exact fix. Items with no runtime warning:
   global reset, test table pagination buttons and search inputs first.
 - **Line chart zero (section 15):** silent behavior change. Audit line chart
   specs manually; y-axis domains will be tighter.
+- **Scatter stroke default (section 20):** silent visual change, and only on
+  themes with an opaque dark background. Set `mark.stroke` explicitly to opt
+  out.

packages/core/src/theme/dark-mode.ts

@@ -6,7 +6,7 @@
  */
 
 import { hsl, rgb } from 'd3-color';
-import { contrastRatio } from '../colors/contrast';
+import { contrastRatio, isOpaqueColor } from '../colors/contrast';
 import { ACHROMATIC_RAMP } from '../colors/palettes';
 import type { ResolvedTheme } from '../types/theme';
 import { DEFAULT_THEME } from './defaults';
@@ -108,9 +108,10 @@ function _luminanceFromHex(color: string): number {
 export function adaptTheme(theme: ResolvedTheme): ResolvedTheme {
   const pairs = theme._tokenPairs;
   const inputBg = theme.colors.background;
-  // "transparent" preserves the background token but must still adopt dark
-  // text/gridline/axis colors — the container is dark, not the chart canvas.
-  const isTransparent = inputBg === 'transparent';
+  // A non-opaque background ('transparent', 'none', alpha-zero rgba) preserves
+  // the background token but must still adopt dark text/gridline/axis colors —
+  // the container is dark, not the chart canvas.
+  const isTransparent = !isOpaqueColor(inputBg);
   const alreadyDark = isTransparent || _luminanceFromHex(inputBg) < 0.2;
 
   // Preserve user-supplied background (including transparent) but always

packages/core/src/theme/resolve.ts

@@ -10,6 +10,7 @@
  * enabling darkMode.
  */
 
+import { isOpaqueColor } from '../colors/contrast';
 import type { ChromeThemeOverride, ThemeConfig } from '../types/spec';
 import type { ChromeDefaults, ResolvedTheme, Theme, TokenValue } from '../types/theme';
 import { DEFAULT_THEME } from './defaults';
@@ -192,9 +193,10 @@ function relativeLuminance(hex: string): number {
 
 /** Returns true if the hex color is perceptually dark (luminance < 0.2). */
 function isDarkBackground(hex: string): boolean {
-  // Transparent has no intrinsic luminance — don't treat it as dark so
-  // light-mode chrome text defaults don't get inverted.
-  if (hex === 'transparent') return false;
+  // A non-opaque background ('transparent', 'none', alpha-zero rgba) has no
+  // intrinsic luminance — don't treat it as dark so light-mode chrome text
+  // defaults don't get inverted.
+  if (!isOpaqueColor(hex)) return false;
   return relativeLuminance(hex) < 0.2;
 }
 

packages/engine/src/charts/scatter/__tests__/compute.test.ts

@@ -501,6 +501,23 @@ describe('computeScatterMarks', () => {
       expect(marks.every((m) => m.stroke === '#ffffff')).toBe(true);
     });
 
+    it('keeps the white stroke for any non-opaque background, not just the literal "transparent"', () => {
+      // 'none' and alpha-zero rgba are truthy but paint nothing. Passing them
+      // through as the stroke would be invisible in SVG and worse on canvas,
+      // where an invalid strokeStyle is silently ignored and the previous
+      // color keeps painting.
+      const spec: NormalizedChartSpec = {
+        ...baseSpec,
+        markDef: { type: 'point' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      for (const background of ['none', 'rgba(0, 0, 0, 0)', 'rgba(9, 9, 11, 0.5)']) {
+        const theme = { colors: { background } } as ResolvedTheme;
+        const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy, theme);
+        expect(marks.every((m) => m.stroke === '#ffffff')).toBe(true);
+      }
+    });
+
     it('lets an explicit mark.stroke override the theme default', () => {
       const spec: NormalizedChartSpec = {
         ...baseSpec,

packages/engine/src/charts/scatter/compute.ts

@@ -17,6 +17,7 @@ import type {
   Rect,
   ResolvedTheme,
 } from '@opendata-ai/openchart-core';
+import { isOpaqueColor } from '@opendata-ai/openchart-core';
 import type { ScaleBand, ScaleLinear, ScalePoint, ScaleTime } from 'd3-scale';
 import { buildSizeScale, SIZE_SCALE_DEFAULTS } from '../../compile/size-scale';
 import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
@@ -133,10 +134,13 @@ export function computeScatterMarks(
   // Default point separator stroke. The classic white halo reads as a bright
   // grid of rings on a dark canvas, so match the stroke to the resolved theme
   // background when it's opaque enough to sit behind the dots (dark mode ->
-  // dark stroke). A transparent background (light mode) keeps the white halo,
-  // which is what gives dots separation on a light ground.
+  // dark stroke). A non-opaque background ('transparent', 'none', alpha-zero
+  // rgba) keeps the white halo: it has no color of its own to match, and
+  // passing a value like 'none' through as a stroke is worse than cosmetic --
+  // canvas silently ignores invalid strokeStyle assignments and keeps painting
+  // with whatever color was set last.
   const bg = theme?.colors?.background;
-  const defaultStroke = bg && bg !== 'transparent' ? bg : '#ffffff';
+  const defaultStroke = bg && isOpaqueColor(bg) ? bg : '#ffffff';
 
   const keyEnc = encoding.key && 'field' in encoding.key ? encoding.key : undefined;
   const keyField = keyEnc?.field;