@mosaicajs/deck 0.3.0 → 0.4.0

package/dist/colour.d.ts

@@ -11,8 +11,17 @@ import type { CategoryValue, Ranks, ScalarColumn } from '@mosaicajs/client';
 type Rgba = readonly [number, number, number, number];
 /** An RGB colour, each channel 0–255. */
 export type Rgb = readonly [number, number, number];
-/** The colour of every mark when no column is encoded. */
-export declare const UNIFORM: Rgba;
+/**
+ * The colour of every mark when no column is encoded, per ground: the theme's secondary ink on a
+ * light ground and a pale blue on a dark one. Against its ground's default background (`#f6f6f4`
+ * and `#111317`) the grey stands 3.8:1 at its own alpha and 2.8:1 at the alpha a mark is
+ * composited at while ten thousand or fewer are drawn, and the blue 6.2:1 and 4.4:1. Past that
+ * the marks turn more translucent and are read as a density, where they overlap.
+ *
+ * The grey is close to {@link UNMAPPED}, which is drawn only while a column colours the marks, so
+ * the two are never drawn together.
+ */
+export declare const UNIFORM: Record<'light' | 'dark', Rgba>;
 /**
  * Everything unmappable: the absent sentinel (code 0), a number with no value, a code no key
  * explains, and any value past the palette's end. A low-saturation grey that reads as "no value"
@@ -116,9 +125,13 @@ export type Colouring = {
  * @category Colour
  */
 export declare const DEFAULT_COLOURING: Colouring;
-/** How a column is being coloured. `uniform` is the default and the fallback for anything unmapped. */
+/**
+ * How a column is being coloured. `uniform` is the default and the fallback for anything unmapped:
+ * one colour, chosen for the ground the marks are drawn on.
+ */
 export type Encoding = {
     kind: 'uniform';
+    ground: 'light' | 'dark';
 } | {
     kind: 'unmapped';
 } | {

package/dist/colour.js

@@ -1,7 +1,16 @@
 import { hasValue, numericValues, rankedValues } from '@mosaicajs/client/internal';
 const ALPHA = 200;
-/** The colour of every mark when no column is encoded. */
-export const UNIFORM = [120, 190, 255, ALPHA];
+/**
+ * The colour of every mark when no column is encoded, per ground: the theme's secondary ink on a
+ * light ground and a pale blue on a dark one. Against its ground's default background (`#f6f6f4`
+ * and `#111317`) the grey stands 3.8:1 at its own alpha and 2.8:1 at the alpha a mark is
+ * composited at while ten thousand or fewer are drawn, and the blue 6.2:1 and 4.4:1. Past that
+ * the marks turn more translucent and are read as a density, where they overlap.
+ *
+ * The grey is close to {@link UNMAPPED}, which is drawn only while a column colours the marks, so
+ * the two are never drawn together.
+ */
+export const UNIFORM = { light: [86, 92, 100, ALPHA], dark: [120, 190, 255, ALPHA] };
 /**
  * Everything unmappable: the absent sentinel (code 0), a number with no value, a code no key
  * explains, and any value past the palette's end. A low-saturation grey that reads as "no value"
@@ -68,6 +77,7 @@ export const DEFAULT_COLOURING = { palette: 'tableau10', ramp: 'viridis', scale:
 export function encodingSignature(encoding) {
     switch (encoding.kind) {
         case 'uniform':
+            return `uniform|${encoding.ground}`;
         case 'unmapped':
             return encoding.kind;
         case 'category': {
@@ -158,7 +168,7 @@ export function lighter(c, amount) {
 export function writeColours(out, offset, count, column, encoding) {
     const out32 = new Uint32Array(out.buffer, out.byteOffset + offset * 4, count);
     if (encoding.kind === 'uniform' || encoding.kind === 'unmapped') {
-        out32.fill(packRgba(encoding.kind === 'uniform' ? UNIFORM : UNMAPPED));
+        out32.fill(packRgba(encoding.kind === 'uniform' ? UNIFORM[encoding.ground] : UNMAPPED));
         return;
     }
     if (!column) {

package/dist/internal.d.ts

@@ -2,7 +2,7 @@
  * `@mosaicajs/deck/internal`: what `@mosaicajs/components` uses of this package beyond the root
  * entry. It is not a public API, and its exports change with the components.
  */
-export { clusterLayerOf, contourShapes, drawnLevel, encodingOf, type MosaicaLayerInternalProps } from './layer.js';
+export { clusterLayerOf, colourLayerOf, contourShapes, drawnLevel, drawnLevels, encodingOf, levelsKey, type MosaicaLayerInternalProps } from './layer.js';
 export { MarkSlab } from './slab.js';
 export { artifactOfMark } from './pick.js';
 export { UNMAPPED, colourOfFraction, colourOfRank, css, encodingSignature, fractionOf, hexOf, lighter, paletteValues, rampAt, rgbOfHex, valueAtFraction } from './colour.js';

package/dist/internal.js

@@ -2,7 +2,7 @@
  * `@mosaicajs/deck/internal`: what `@mosaicajs/components` uses of this package beyond the root
  * entry. It is not a public API, and its exports change with the components.
  */
-export { clusterLayerOf, contourShapes, drawnLevel, encodingOf } from './layer.js';
+export { clusterLayerOf, colourLayerOf, contourShapes, drawnLevel, drawnLevels, encodingOf, levelsKey } from './layer.js';
 export { MarkSlab } from './slab.js';
 export { artifactOfMark } from './pick.js';
 export { UNMAPPED, colourOfFraction, colourOfRank, css, encodingSignature, fractionOf, hexOf, lighter, paletteValues, rampAt, rgbOfHex, valueAtFraction } from './colour.js';

package/dist/layer.d.ts

@@ -44,16 +44,20 @@ export type MosaicaLayerProps = CompositeLayerProps & {
      */
     status?: PresentedStatus;
     /**
-     * The level of a `stacked` or `tiered` artifact layer to colour, name and outline artifacts at.
-     * Defaults to the coarsest level served. On a `nested` or `dag` layer it has no default, and each
-     * mark takes the nearest artifact served.
+     * The level to colour, name and outline each `stacked` or `tiered` artifact layer at, keyed by
+     * layer name. A layer with no entry is drawn at its entry in the artifacts projection's
+     * `followedLevels`: where its levels declare no zoom range, the finest level that is not crowded
+     * in view, which deepens as the map zooms in, and otherwise the coarsest level the camera's zoom
+     * serves. A `nested` or `dag` layer takes no level, whatever its entry, and each mark takes the
+     * nearest artifact served.
      */
-    clusterLevel?: number;
+    clusterLevels?: ReadonlyMap<string, number>;
     /** Whether to draw the artifacts' names, with the count of the one under the pointer. Defaults to `true`. */
     labels?: boolean;
     /**
      * Whether the map's background is `light` or `dark`. The colours of names, outlines, the
-     * picked mark's ring and the selected region are chosen to suit it. Defaults to `dark`.
+     * picked mark's ring, the selected region and the points while no column colours them are
+     * chosen to suit it. Defaults to `dark`.
      */
     scheme?: 'light' | 'dark';
     /**
@@ -190,20 +194,28 @@ export type LayerTimings = {
 };
 /** A layer's colouring, as the store's `colourBy` names it: `cluster:<layer>` or a column. */
 export declare function clusterLayerOf(colourBy: string | null | undefined): string | null;
+/** The layer marks are coloured from: the layer coloured by, else the first layer drawn. */
+export declare function colourLayerOf(artifacts: Pick<ArtifactsProjection, 'layers'> | null, colourBy: string | null | undefined): string | undefined;
 /**
- * The level clusters are coloured, named and outlined at: `chosen` where given, else the top
- * (coarsest) level served at the camera's zoom of the layer coloured by, or of the first layer
- * drawn, where that layer is `stacked` or `tiered`. On any other layer, `undefined`: each point
- * takes its nearest served cluster.
+ * The level the layer `name` is coloured, named and outlined at, where it is `stacked` or `tiered`:
+ * its entry in `chosen` where the layer declares that level, else its entry in the projection's
+ * `followedLevels`: the finest level not crowded in view where no level declares a zoom range,
+ * else the coarsest served at the camera's zoom. On a layer of any other kind, or one missing from
+ * the roster, `undefined`: each point takes its nearest served cluster.
  */
-export declare function drawnLevel(meta: Meta | null, artifacts: Pick<ArtifactsProjection, 'layers' | 'served'> | null, colourBy: string | null | undefined, chosen: number | undefined): number | undefined;
+export declare function drawnLevel(meta: Meta | null, artifacts: Pick<ArtifactsProjection, 'followedLevels'> | null, name: string | undefined, chosen: ReadonlyMap<string, number> | undefined): number | undefined;
+/** {@link drawnLevel} for each layer drawn, keyed by name. A layer drawn at no level has no entry. */
+export declare function drawnLevels(meta: Meta | null, artifacts: Pick<ArtifactsProjection, 'layers' | 'followedLevels'> | null, chosen: ReadonlyMap<string, number> | undefined): Map<string, number>;
+/** A cache key for a set of {@link drawnLevels}. */
+export declare function levelsKey(levels: ReadonlyMap<string, number>): string;
 /**
  * The current column colour encoding, from the store's legend, the schema and the colour choices.
- * Uniform where nothing is ready to colour by yet, such as a column chosen before any of its codes
- * were counted. Unmapped where `/v1/categories` refused the column, so the legend can say the
- * values could not be named. A chosen value colour applies once the legend has named its key.
+ * Uniform, in the one colour for `ground`, where nothing is ready to colour by yet, such as a
+ * column chosen before any of its codes were counted. Unmapped where `/v1/categories` refused the
+ * column, so the legend can say the values could not be named. A chosen value colour applies once
+ * the legend has named its key.
  */
-export declare function encodingOf(meta: Meta | null, legend: LegendProjection | null, colouring?: Colouring): Encoding;
+export declare function encodingOf(meta: Meta | null, legend: LegendProjection | null, colouring?: Colouring, ground?: 'light' | 'dark'): Encoding;
 /** What a density image is built for: one set of counts, drawn as a wash or a grid on one scale, in one set of colours on one ground. */
 type WashKey = {
     counts: DensityCounts;
@@ -255,14 +267,19 @@ export type OutlineDatum = {
 export type OutlineOptions = {
     opened: bigint | null;
     hovered: bigint | null;
-    level: number | undefined;
+    /** The level each layer is cut at ({@link drawnLevels}). */
+    levels: ReadonlyMap<string, number>;
     scheme: 'light' | 'dark';
-    /** The layer roster, to leave a dependent layer's artifacts out; null draws every served layer. */
+    /**
+     * The layer roster, to leave a dependent layer's artifacts out and to draw a `stacked` layer at
+     * its level alone; null draws every served layer.
+     */
     meta?: Meta | null;
 };
-/** The level cut, the layer roster and the opened artifact, which decide what may be hovered. */
+/** The level cuts, the layer roster and the opened artifact, which decide what may be hovered. */
 export type ContourOptions = {
-    level: number | undefined;
+    /** The level each layer is cut at ({@link drawnLevels}). */
+    levels: ReadonlyMap<string, number>;
     meta?: Meta | null;
     /** The opened artifact, which may be pointed at whether or not a filter matches it. */
     opened?: bigint | null;
@@ -314,30 +331,32 @@ export type LabelText = {
     topic: string | null;
 };
 /**
- * The artifacts named at `level`: every drawn artifact with no drawn child. An artifact with a
+ * The artifacts named at `levels`: every drawn artifact with no drawn child. An artifact with a
  * drawn child is an ancestor of something on the map and is not labelled.
  *
- * With no level this is the leaves of the served set. With one it is that level's artifacts and
- * every shallower artifact whose children are all deeper than the level, so a branch that ends
- * above the level is still named. The level compared is the served `rung`, which the server
- * computes per layer kind; a levelled layer's edges may skip a level, so a client-side depth count
- * would be wrong.
+ * On a layer with no entry in `levels` this is the leaves of its served set. On one with an entry
+ * it is that level's artifacts and every shallower artifact whose children are all deeper than the
+ * level, so a branch that ends above the level is still named. A `stacked` layer in `meta` has no
+ * edges between its levels, so on one with an entry it is that level's artifacts alone. Each layer
+ * is cut at its own entry only. The level compared is the served `rung`, which the server computes
+ * per layer kind; a levelled layer's edges may skip a level, so a client-side depth count would be
+ * wrong.
  *
  * Under a filter, an artifact with no member in view that matches it is left out: none of its
  * points are drawn, so its name and its outline would stand over empty ground. A parent whose
  * children all match nothing is on the frontier in their place.
  */
-export declare function frontier(a: ArtifactsProjection, level: number | undefined, opened?: bigint | null): Set<bigint>;
+export declare function frontier(a: ArtifactsProjection, levels: ReadonlyMap<string, number>, opened?: bigint | null, meta?: Meta | null): Set<bigint>;
 /**
  * The label candidates for a served set at `zoom`: the top `budget` frontier artifacts by masked
  * count that have text to draw, each with its name, count, topic and pixel box. An artifact with
  * no text and no attached topic gets no label; its key is an identifier, not a name. Name size
  * comes from {@link labelSize} over the candidates' counts.
  *
- * Only the anchor depends on the zoom, so the list is built once per served set, level and budget,
+ * Only the anchor depends on the zoom, so the list is built once per served set, levels and budget,
  * and each zoom bucket scales the anchors into a copy.
  */
-export declare function labelCandidates(a: ArtifactsProjection, meta: Meta | null, level: number | undefined, zoom: number, budget: number, opened?: bigint | null): {
+export declare function labelCandidates(a: ArtifactsProjection, meta: Meta | null, levels: ReadonlyMap<string, number>, zoom: number, budget: number, opened?: bigint | null): {
     candidates: LabelCandidate[];
     byId: Map<bigint, LabelText>;
 };
@@ -379,8 +398,8 @@ export type MosaicaLayerInternalProps = MosaicaLayerProps & {
  * to {@link resolvePick} to find the item or artifact under the pointer, then set the props that
  * show it, such as `selectedWorldXY` and `hoveredArtifact`. If the artifact's layer declares
  * shapes, call the store's `needShape` with its id: the outline appears once the shape arrives.
- * Otherwise the outline is the artifact's bounding box. Only an artifact drawn at `clusterLevel`
- * is outlined.
+ * Otherwise the outline is the artifact's bounding box. Only an artifact drawn at its layer's level
+ * (`clusterLevels`) is outlined.
  */
 export declare class MosaicaLayer extends CompositeLayer<MosaicaLayerInternalProps> {
     /** @internal */
@@ -395,7 +414,7 @@ export declare class MosaicaLayer extends CompositeLayer<MosaicaLayerInternalPro
         legend: null;
         status: string;
         slab: null;
-        clusterLevel: undefined;
+        clusterLevels: undefined;
         labels: boolean;
         scheme: string;
         selectedWorldXY: null;
@@ -484,8 +503,10 @@ export declare class MosaicaLayer extends CompositeLayer<MosaicaLayerInternalPro
      * estimated width plus the fade at both ends. Present from the first paint, empty, like the text.
      */
     private backingLayer;
-    /** The level clusters are drawn at ({@link drawnLevel}). */
-    private levelOf;
+    /** The level marks are coloured at: that of the layer they are coloured from ({@link colourLayerOf}). */
+    private colourLevel;
+    /** The level each drawn layer is cut at ({@link drawnLevels}). */
+    private levels;
     /**
      * Whether the labels sit on opaque plates with no halo: while density is drawn as hexagons or a
      * grid, or as a smooth wash in a ramp, whose colours fill the ground under the names.

package/dist/layer.js

@@ -1,7 +1,7 @@
 import { CompositeLayer } from '@deck.gl/core';
 import { BitmapLayer, ColumnLayer, IconLayer, LineLayer, PolygonLayer, ScatterplotLayer, TextLayer } from '@deck.gl/layers';
 import { CLUSTER_PREFIX, NO_ORDINAL, artifactName, WORLD_SIZE, gridToWorld, gridToWorldXY } from '@mosaicajs/client';
-import { NEUTRAL, topLevelServed } from '@mosaicajs/client/internal';
+import { NEUTRAL, levelOfLayer } from '@mosaicajs/client/internal';
 import { materialiseStandIn } from './assemble.js';
 import { BACKING_HEIGHT_EM, backingAspect, backingAtlas, backingIcon } from './backing.js';
 import { DEFAULT_COLOURING, buildColourAttribute, encodingSignature, rgbOfHex } from './colour.js';
@@ -21,18 +21,34 @@ const LABEL_ZOOM_STEP = 4;
 export function clusterLayerOf(colourBy) {
     return colourBy && colourBy.startsWith(CLUSTER_PREFIX) ? colourBy.slice(CLUSTER_PREFIX.length) : null;
 }
+/** The layer marks are coloured from: the layer coloured by, else the first layer drawn. */
+export function colourLayerOf(artifacts, colourBy) {
+    return clusterLayerOf(colourBy) ?? artifacts?.layers[0];
+}
 /**
- * The level clusters are coloured, named and outlined at: `chosen` where given, else the top
- * (coarsest) level served at the camera's zoom of the layer coloured by, or of the first layer
- * drawn, where that layer is `stacked` or `tiered`. On any other layer, `undefined`: each point
- * takes its nearest served cluster.
+ * The level the layer `name` is coloured, named and outlined at, where it is `stacked` or `tiered`:
+ * its entry in `chosen` where the layer declares that level, else its entry in the projection's
+ * `followedLevels`: the finest level not crowded in view where no level declares a zoom range,
+ * else the coarsest served at the camera's zoom. On a layer of any other kind, or one missing from
+ * the roster, `undefined`: each point takes its nearest served cluster.
  */
-export function drawnLevel(meta, artifacts, colourBy, chosen) {
-    if (chosen !== undefined)
-        return chosen;
-    const name = clusterLayerOf(colourBy) ?? artifacts?.layers[0];
+export function drawnLevel(meta, artifacts, name, chosen) {
     const layer = name === undefined ? undefined : meta?.layers.find((l) => l.name === name);
-    return layer ? topLevelServed(layer, artifacts?.served ?? []) : undefined;
+    return layer ? levelOfLayer(layer, chosen?.get(layer.name), artifacts?.followedLevels) : undefined;
+}
+/** {@link drawnLevel} for each layer drawn, keyed by name. A layer drawn at no level has no entry. */
+export function drawnLevels(meta, artifacts, chosen) {
+    const out = new Map();
+    for (const name of artifacts?.layers ?? []) {
+        const level = drawnLevel(meta, artifacts, name, chosen);
+        if (level !== undefined)
+            out.set(name, level);
+    }
+    return out;
+}
+/** A cache key for a set of {@link drawnLevels}. */
+export function levelsKey(levels) {
+    return [...levels].map(([name, level]) => `${name}@${level}`).join(',');
 }
 /** The selected region's colour per ground: the interface's ink, since colour on the map is data's. */
 const ACCENT = { light: [27, 29, 33], dark: [236, 238, 241] };
@@ -85,17 +101,19 @@ const CHROME = [234, 238, 243, 240];
 const PLATE = [13, 15, 18, 235];
 /**
  * The current column colour encoding, from the store's legend, the schema and the colour choices.
- * Uniform where nothing is ready to colour by yet, such as a column chosen before any of its codes
- * were counted. Unmapped where `/v1/categories` refused the column, so the legend can say the
- * values could not be named. A chosen value colour applies once the legend has named its key.
+ * Uniform, in the one colour for `ground`, where nothing is ready to colour by yet, such as a
+ * column chosen before any of its codes were counted. Unmapped where `/v1/categories` refused the
+ * column, so the legend can say the values could not be named. A chosen value colour applies once
+ * the legend has named its key.
  */
-export function encodingOf(meta, legend, colouring = DEFAULT_COLOURING) {
+export function encodingOf(meta, legend, colouring = DEFAULT_COLOURING, ground = 'dark') {
+    const uniform = { kind: 'uniform', ground };
     const colourBy = legend?.colourBy ?? null;
     if (!colourBy || !meta || !legend || colourBy.startsWith(CLUSTER_PREFIX))
-        return { kind: 'uniform' };
+        return uniform;
     const column = meta.declaredScalars.find((c) => c.name === colourBy);
     if (!column)
-        return { kind: 'uniform' };
+        return uniform;
     if (legend.categoryErrors[colourBy])
         return { kind: 'unmapped' };
     if (column.category) {
@@ -103,7 +121,7 @@ export function encodingOf(meta, legend, colouring = DEFAULT_COLOURING) {
         // for `/v1/categories`, which only names the legend's entries.
         const rankOfCode = legend.ranks[colourBy];
         if (!rankOfCode || Object.keys(rankOfCode).length === 0)
-            return { kind: 'uniform' };
+            return uniform;
         const chosen = new Map();
         const picked = colouring.values[colourBy];
         if (picked) {
@@ -117,7 +135,7 @@ export function encodingOf(meta, legend, colouring = DEFAULT_COLOURING) {
     }
     const domain = legend.domains[colourBy];
     if (!domain)
-        return { kind: 'uniform' };
+        return uniform;
     return { kind: 'numeric', column: colourBy, domain, ramp: colouring.ramp, scale: colouring.scale, reverse: colouring.reverse };
 }
 const descriptors = new WeakMap();
@@ -200,16 +218,24 @@ const OPENED_LINE = 200;
  */
 const BOX_LINE_WIDTH = 0.8;
 /**
- * Whether a served artifact is drawn at `level` and has no drawn child: {@link frontier}'s rule for
- * one artifact. Under a filter, one with no matching member in view is not drawn, except `opened`,
- * which the viewer chose.
+ * Whether a served artifact is drawn at its layer's entry in `levels` and has no drawn child:
+ * {@link frontier}'s rule for one artifact. Under a filter, one with no matching member in view is
+ * not drawn, except `opened`, which the viewer chose.
  */
-function onFrontier(a, artifact, level, opened = null) {
-    const drawn = (x) => (x.matched !== false || x.mosaicaId === opened) && (level === undefined || x.rung <= level);
+function onFrontier(a, artifact, levels, opened, stacked) {
+    const drawn = (x) => {
+        const level = levels.get(x.layer);
+        const atLevel = level === undefined || (stacked.has(x.layer) ? x.rung === level : x.rung <= level);
+        return (x.matched !== false || x.mosaicaId === opened) && atLevel;
+    };
     if (!drawn(artifact))
         return false;
     return !(a.lineage.childrenOf.get(artifact.mosaicaId) ?? []).some((c) => drawn(c));
 }
+/** The `stacked` layers of the roster, whose levels are drawn one at a time. */
+function stackedLayers(meta) {
+    return new Set(meta?.layers.filter((l) => l.hierarchy.kind === 'stacked').map((l) => l.name) ?? []);
+}
 /** The layers whose artifacts attach their text to another layer's, and draw no shape of their own. */
 function dependentLayers(meta) {
     return new Set(meta?.layers.filter((l) => l.depsOn.length > 0).map((l) => l.name) ?? []);
@@ -230,7 +256,7 @@ function shapeKindOf(meta, layer) {
  */
 export function contourShapes(a, o) {
     const dependent = dependentLayers(o.meta);
-    const front = frontier(a, o.level, o.opened ?? null);
+    const front = frontier(a, o.levels, o.opened ?? null, o.meta);
     const shapes = [];
     for (const artifact of a.served) {
         if (!front.has(artifact.mosaicaId))
@@ -260,6 +286,7 @@ export function contourShapes(a, o) {
  */
 export function focusOutlines(a, o) {
     const dependent = dependentLayers(o.meta);
+    const stacked = stackedLayers(o.meta);
     const data = [];
     const seen = new Set();
     // Opened first, so the artifact under the pointer draws as opened once it is opened.
@@ -272,7 +299,7 @@ export function focusOutlines(a, o) {
             continue;
         if (dependent.has(artifact.layer))
             continue;
-        if (!onFrontier(a, artifact, o.level, o.opened))
+        if (!onFrontier(a, artifact, o.levels, o.opened, stacked))
             continue;
         const outline = outlineOf(artifact, a.shapes?.get(id));
         if (!outline)
@@ -328,23 +355,26 @@ const COUNT_GAP_EM = 0.35;
 /** The topic line beneath the name, in pixels. */
 const TOPIC_SIZE = 12;
 /**
- * The artifacts named at `level`: every drawn artifact with no drawn child. An artifact with a
+ * The artifacts named at `levels`: every drawn artifact with no drawn child. An artifact with a
  * drawn child is an ancestor of something on the map and is not labelled.
  *
- * With no level this is the leaves of the served set. With one it is that level's artifacts and
- * every shallower artifact whose children are all deeper than the level, so a branch that ends
- * above the level is still named. The level compared is the served `rung`, which the server
- * computes per layer kind; a levelled layer's edges may skip a level, so a client-side depth count
- * would be wrong.
+ * On a layer with no entry in `levels` this is the leaves of its served set. On one with an entry
+ * it is that level's artifacts and every shallower artifact whose children are all deeper than the
+ * level, so a branch that ends above the level is still named. A `stacked` layer in `meta` has no
+ * edges between its levels, so on one with an entry it is that level's artifacts alone. Each layer
+ * is cut at its own entry only. The level compared is the served `rung`, which the server computes
+ * per layer kind; a levelled layer's edges may skip a level, so a client-side depth count would be
+ * wrong.
  *
  * Under a filter, an artifact with no member in view that matches it is left out: none of its
  * points are drawn, so its name and its outline would stand over empty ground. A parent whose
  * children all match nothing is on the frontier in their place.
  */
-export function frontier(a, level, opened = null) {
+export function frontier(a, levels, opened = null, meta = null) {
+    const stacked = stackedLayers(meta);
     const out = new Set();
     for (const artifact of a.served)
-        if (onFrontier(a, artifact, level, opened))
+        if (onFrontier(a, artifact, levels, opened, stacked))
             out.add(artifact.mosaicaId);
     return out;
 }
@@ -354,27 +384,27 @@ export function frontier(a, level, opened = null) {
  * no text and no attached topic gets no label; its key is an identifier, not a name. Name size
  * comes from {@link labelSize} over the candidates' counts.
  *
- * Only the anchor depends on the zoom, so the list is built once per served set, level and budget,
+ * Only the anchor depends on the zoom, so the list is built once per served set, levels and budget,
  * and each zoom bucket scales the anchors into a copy.
  */
-export function labelCandidates(a, meta, level, zoom, budget, opened = null) {
-    const key = `${a.version}|${level ?? ''}|${budget}|${opened ?? ''}`;
+export function labelCandidates(a, meta, levels, zoom, budget, opened = null) {
+    const key = `${a.version}|${levelsKey(levels)}|${budget}|${opened ?? ''}`;
     let held = heldCandidates.get(a.served);
     if (!held || held.key !== key) {
-        held = { key, ...namedCandidates(a, meta, level, budget, opened) };
+        held = { key, ...namedCandidates(a, meta, levels, budget, opened) };
         heldCandidates.set(a.served, held);
     }
     const scale = 2 ** zoom; // pixels per world unit
     return { candidates: held.candidates.map((c) => ({ ...c, x: c.x * scale, y: c.y * scale })), byId: held.byId };
 }
 /** {@link labelCandidates} with anchors in world units, which the caller scales. */
-function namedCandidates(a, meta, level, budget, opened) {
+function namedCandidates(a, meta, levels, budget, opened) {
     const placed = a.served.filter((x) => x.centroid !== null);
     // A dependent layer's artifacts (a clustering's topic labels) are drawn beneath their target's
     // name and are not candidates of their own.
     const dependent = new Set(meta?.layers.filter((l) => l.depsOn.length > 0).map((l) => l.name) ?? []);
     // The same frontier the hover shapes use, so a name and the shape it labels agree.
-    const front = frontier(a, level, opened);
+    const front = frontier(a, levels, opened, meta);
     const named = placed
         .filter((x) => !dependent.has(x.layer) && front.has(x.mosaicaId))
         .filter((x) => artifactName(x, a.attached) !== null)
@@ -455,8 +485,8 @@ export function outlineOf(a, fetched) {
  * to {@link resolvePick} to find the item or artifact under the pointer, then set the props that
  * show it, such as `selectedWorldXY` and `hoveredArtifact`. If the artifact's layer declares
  * shapes, call the store's `needShape` with its id: the outline appears once the shape arrives.
- * Otherwise the outline is the artifact's bounding box. Only an artifact drawn at `clusterLevel`
- * is outlined.
+ * Otherwise the outline is the artifact's bounding box. Only an artifact drawn at its layer's level
+ * (`clusterLevels`) is outlined.
  */
 export class MosaicaLayer extends CompositeLayer {
     /** @internal */
@@ -471,7 +501,7 @@ export class MosaicaLayer extends CompositeLayer {
         legend: null,
         status: 'idle',
         slab: null,
-        clusterLevel: undefined,
+        clusterLevels: undefined,
         labels: true,
         scheme: 'dark',
         selectedWorldXY: null,
@@ -655,7 +685,7 @@ export class MosaicaLayer extends CompositeLayer {
         const r = this.resolved();
         const slab = this.slab();
         const layers = [];
-        // The key covers the palette, level and highlight; `update` compares the table and colour map
+        // The key covers the palette, colour level and highlight; `update` compares the table and colour map
         // itself. No texel depends on the served set's version, so it is not in the key.
         const lut = this.lut();
         const lutStarted = performance.now();
@@ -663,7 +693,7 @@ export class MosaicaLayer extends CompositeLayer {
         const highlight = r.artifacts && opened !== null ? r.artifacts.served.find((a) => a.mosaicaId === opened) : undefined;
         const highlightOrdinal = highlight && r.artifacts ? r.artifacts.table.ordinalOf(highlight.layer, highlight.mosaicaId) : NO_ORDINAL;
         if (r.artifacts) {
-            lut.update({ artifacts: r.artifacts, level: this.levelOf(r), highlight: highlightOrdinal }, `${r.artifacts.palette}|${this.levelOf(r) ?? ''}|${highlightOrdinal}`);
+            lut.update({ artifacts: r.artifacts, level: this.colourLevel(r), highlight: highlightOrdinal }, `${r.artifacts.palette}|${this.colourLevel(r) ?? ''}|${highlightOrdinal}`);
         }
         timings.lutMs = performance.now() - lutStarted;
         // A refusal draws no marks but keeps the slab, whose bands answer the last view that
@@ -685,9 +715,10 @@ export class MosaicaLayer extends CompositeLayer {
         // texture, so switching to it leaves the attribute holding the last column encoding.
         const colourBy = r.legend?.colourBy ?? null;
         const clusterLayer = clusterLayerOf(colourBy);
-        let column = heldColumnEncoding.get(slab) ?? { encoding: { kind: 'uniform' }, colourBy: null };
+        const ground = this.props.scheme ?? 'dark';
+        let column = heldColumnEncoding.get(slab) ?? { encoding: { kind: 'uniform', ground }, colourBy: null };
         if (!clusterLayer) {
-            column = { encoding: encodingOf(r.meta, r.legend, this.props.colouring ?? DEFAULT_COLOURING), colourBy };
+            column = { encoding: encodingOf(r.meta, r.legend, this.props.colouring ?? DEFAULT_COLOURING, ground), colourBy };
             heldColumnEncoding.set(slab, column);
         }
         const encoding = column.encoding;
@@ -897,9 +928,13 @@ export class MosaicaLayer extends CompositeLayer {
             updateTriggers: { getIcon: key, getSize: key, getPixelOffset: key, getColor: scheme }
         });
     }
-    /** The level clusters are drawn at ({@link drawnLevel}). */
-    levelOf(r) {
-        return drawnLevel(r.meta, r.artifacts, r.legend?.colourBy, this.props.clusterLevel);
+    /** The level marks are coloured at: that of the layer they are coloured from ({@link colourLayerOf}). */
+    colourLevel(r) {
+        return drawnLevel(r.meta, r.artifacts, colourLayerOf(r.artifacts, r.legend?.colourBy), this.props.clusterLevels);
+    }
+    /** The level each drawn layer is cut at ({@link drawnLevels}). */
+    levels(r) {
+        return drawnLevels(r.meta, r.artifacts, this.props.clusterLevels);
     }
     /**
      * Whether the labels sit on opaque plates with no halo: while density is drawn as hexagons or a
@@ -1061,10 +1096,11 @@ export class MosaicaLayer extends CompositeLayer {
         const opened = this.props.openedArtifact ?? null;
         const hovered = this.props.hoveredArtifact ?? null;
         const scheme = this.props.scheme ?? 'dark';
-        const key = a ? `${a.version}|${a.palette}|${opened ?? ''}|${hovered ?? ''}|${scheme}|${this.levelOf(r) ?? ''}` : '';
+        const levels = this.levels(r);
+        const key = a ? `${a.version}|${a.palette}|${opened ?? ''}|${hovered ?? ''}|${scheme}|${levelsKey(levels)}` : '';
         let held = a ? heldOutlines.get(a.served) : undefined;
         if (a && (!held || held.key !== key || held.shapes !== a.shapes)) {
-            held = { key, shapes: a.shapes, data: focusOutlines(a, { opened, hovered, level: this.levelOf(r), scheme, meta: r.meta }) };
+            held = { key, shapes: a.shapes, data: focusOutlines(a, { opened, hovered, levels, scheme, meta: r.meta }) };
             heldOutlines.set(a.served, held);
         }
         const data = held?.data ?? NO_OUTLINES;
@@ -1105,11 +1141,12 @@ export class MosaicaLayer extends CompositeLayer {
         const bucket = Math.round(zoom * LABEL_ZOOM_STEP);
         const budget = a ? labelBudget(a.served.length) : 0;
         const opened = this.props.openedArtifact ?? null;
-        const key = a ? `${a.version}|${a.palette}|${bucket}|${budget}|${this.levelOf(r) ?? ''}|${opened ?? ''}` : '';
+        const levels = this.levels(r);
+        const key = a ? `${a.version}|${a.palette}|${bucket}|${budget}|${levelsKey(levels)}|${opened ?? ''}` : '';
         let held = a ? heldLabels.get(a.served) : undefined;
         if (a && viewport && (!held || held.key !== key)) {
             const scale = 2 ** zoom; // pixels per world unit
-            const { candidates, byId } = labelCandidates(a, r.meta, this.levelOf(r), zoom, budget, opened);
+            const { candidates, byId } = labelCandidates(a, r.meta, levels, zoom, budget, opened);
             const data = [];
             const leaders = [];
             let placed = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaicajs/deck",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A deck.gl layer that draws a Mosaica store, for a host with its own Deck.",
   "keywords": [
     "mosaica",
@@ -45,7 +45,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@mosaicajs/client": "0.3.0"
+    "@mosaicajs/client": "0.4.0"
   },
   "peerDependencies": {
     "@deck.gl/aggregation-layers": "^9.3.7",