Finalize layertype pluginization: attachments, capabilities, config/filter/time surfaces, extends #115

[tariqksoliman]

With Devin: JPL-Devin#115

Purpose

#112 moved map-render dispatch behind LayerTypeRegistry/LayerInterface, but layer-type-specific behavior was still spread across core: ~94 comparisons of a layer's type against built-in ids, globe engine configs built inline in two duplicated blocks in visibility.js, filterer selection keyed by type, and all seven layer attachments constructed by ~1140 lines of hardcoded core code. This finishes the job: a layer type (or attachment) owns everything specific to it, core only dispatches, and manifest capabilities answer the classification questions core must ask while iterating every layer.

The invariant is now enforced by a test rather than by convention: no file under src/ may compare a layer's or attachment's type against a built-in id, or single out a built-in attachment by name (.pairings, sub === 'image_overlays', ['models'].includes(sub)).

Proposed Changes

Layer types own their behavior

• [CHANGE] setVisibility now receives a real context ({visible, wasNeverOn, firstTimeOn, hadToMake, globeOnly, source, ...}), plus onToggle as sugar for setVisibility.after, so the per-type toggle work (Vector's time-filter + initial-filter submit, Velocity's remake, Video's mute, Image's recolor) lives in plugins/core/layertypes/*/map/*.js.
• [CHANGE] Globe layers are built by the plugin, not by core. visibility.js no longer builds LithoSphere/Cesium configs or calls litho.addLayer — each type has globe/config.js + globe/{cesium,lithosphere}/*.js and goes through GlobeRenderer. The two duplicated core blocks had already diverged; where they disagreed the toggle path won (addVisible was applying tile-only throughTileServer/COG: URL rewriting to model/3dtiles).
• [ADD] config, filter and time surfaces: STAC expansion / kind / throughTileServer normalization and URL resolution (config), LocalFilterer/GeodatasetFilterer/ESFilterer selection (filter), and time availability + WMS param stamping (time).
• [ADD] extends (one level) so a type inherits every surface and capability it doesn't define.
• [ADD] Single-file plugins: "module": "./x.js" exporting {map, globe, config, filter, time}. Every op except make has a correct-but-generic core default, so a working type can be one file.
• [ADD] capabilities fields for the questions core asks while partitioning all layers — structural, map.stacking/redrawOnReorder/tracksLoad/refreshByRemake/stacEndpoint/picking/styling, time.histogram, defaultInteractions — replacing the type lists in ordering, picking, header handling and TimeUI eligibility. capabilities.time/filtering/identify were declared in all 11 manifests and read nowhere; they're consumed now.
• [ADD] Layertype/attachment plugins can declare npm dependencies (resolve-plugin-deps.js and checkPluginDependencies skipped both containers).
• [FIX] expandLayers recursed into sublayers without awaiting itself. Latent upstream, but fatal once config.expand made the loop async: dataFlat was still filling when Map_.init ran and only 4 of 66 Reference Mission layers were made.
• [CHANGE] Removed the vestigial type === 'point' check in resetLayerFills. point was a vector alias whose makeLayer case was dropped in eb11ff87, so such a layer has never entered L_.layers.layer since.

Attachments own their construction

• [CHANGE] All seven attachment constructors moved out of LayerConstructors.js (−1692 lines) into their plugins' make. Core's constructSublayers now asks LayerAttachmentRegistry which attachments apply to the host's type, in which order, and which need their siblings:

  const ids = LayerAttachmentRegistry.orderedFor(layerObj.type)
  ids.forEach((id) => { sublayers[sublayerKey(id)] = false })
  // build, deferring buildsAfterSiblings ids (labels) until the rest exist

• [ADD] Attachment ops for the behavior that was left in core: syncData (UncertaintyEllipses' globe teardown, ImageOverlays' z-index), setStyle (CoordinateMarkers' highlight restyle), setOpacity (UncertaintyEllipses' scaled stroke/fill, ImageOverlays' DOM opacity), onPeerToggle (Pairings reacting to a layer it watches), and peerFeaturesFor.

• [ADD] Host metadata in each attachment manifest: render order, sublayerKey (the model attachment is still stored under the legacy models key), buildsAfterSiblings (labels).

• [CHANGE] Photosphere.js no longer reads .pairings state or computes pair az/el itself. It asks L_.getPeerFeatures(layerName, feature, {originOffset}), which dispatches to whichever attachment implements peerFeaturesFor, and plots what comes back.

• [CHANGE] The gradient-polyline globe add/remove (including the in-flight-build guard) moved from sublayers.js into the PathGradient plugin; gradient_polyline remains a GlobeRenderer primitive kind.

Attachments own their settings, their click-mode half and their identity

• [ADD] configPath in every attachment manifest (e.g. image_overlays → variables.markerAttachments.image). An attachment's id, its key on the host and its config key are three different names; declaring the third lets core answer "does this host want this attachment?" once instead of seven copies of F_.getIn(...) + enabled === true || enabled == null.
• [ADD] Bearing is an attachment (the 8th) rather than a hardcoded branch in pointToLayer. It decorates its host instead of building a sublayer, so it declares host.decoratesHost and implements decorateFeature/globeStyle in place of make — and consequently never appears in the host's Composite Layers list.
• [CHANGE] applicableLayerTypes is resolved through one level of extends, and the five attachments that declared no hosts now declare ["vector","query"] — the only hosts that have ever constructed attachments. Configure therefore stops offering attachment settings on vectortile and model layers, where nothing was ever built; values already saved there are preserved on save rather than trimmed.
• [ADD] A config block in every attachment manifest, replacing the four Attachment - * tab-sets copy-pasted into the Vector, VectorTile, Query and Model metaconfigs (three of which had already drifted). Configure fetches layerAttachmentConfigs.json and composes the rows into the same four tabs, so a third-party attachment gets settings UI without editing any layer type.
• [CHANGE] WaypointImage/WaypointModel no longer reimplement the image/model config with their own defaults next to the attachment's. They call L_.makeFeatureAttachment(id, ...), and the plugin owns the show: 'click' half exactly as it owns the always-on half; deselection is L_.clearFeatureAttachments() instead of core knowing the two temp-layer names.
• [CHANGE] The LayersTool's attachment tooltip comes from the manifest description (per-instance title still overrides), so fixing a description fixes the UI.

Enforcement

• [ADD] tests/unit/layerTypeBranchGuardrail.spec.js — no built-in type comparison and no built-in attachment singled out by name under src/. Geometry types ('Point'), time.type, filter value types and menu-item types are inherently out of scope since it only inspects layer/attachment type comparisons.
• [ADD] tests/unit/layerTypeInheritance.spec.js, and updateLayerAttachments.spec.js assertions that every attachment has a valid make, declares a unique host order, and keeps its legacy sublayer key.
• [CHANGE] pluginValidation.js validates per surface (a buildConfig in a map module is an error), enum-checks the new capability fields, and requires make on an attachment — except a host decoration, which has nothing to make.
• [ADD] tests/unit/layerAttachmentTabs.spec.js — every field the composed Configure tabs write lives under some attachment's declared configPath, a type inherits its parent's attachment settings, and a host no attachment applies to gets none.

Authoring: docs, scaffolds and a loud contract

The code grew four new surfaces, a capability vocabulary and a whole family; the authoring materials still described #112's render contract, so the safe path for a new plugin was "copy an existing one".

• [CHANGE] plugin-cli/ is a root-level directory (cli.js, lib/, scaffolds/<type>/), leaving /plugins for containers and plugin-state.json only. registries.json is CLI config and moves with it; the server still reads state from /plugins, so discovery is untouched. npm run plugins -- <cmd> is unchanged.
• [CHANGE] The six scaffolds are real files under plugin-cli/scaffolds/<type>/ instead of ~500 lines of string arrays inside the CLI. create copies the tree, substituting the name into paths and contents (__Name__, __name__, __flatname__, __snake_name__, __colon_name__). Being valid JSON/JS as they sit, they go through the same validator as any plugin — a broken scaffold now fails tests rather than someone's first plugin.
• [ADD] create layerattachment, and plugins/core/layerattachments/README.md with the contract, every op and the core default it replaces, the capability table and a worked example. It was the one family with neither a scaffold nor a README.
• [ADD] Capability validation against a schema: a wrong leaf type or an out-of-enum value is an error, an unknown key warns (forward compatibility), and an omission core acts on (map.stacking on a map-rendering type, host.order on a non-decoration attachment) warns. These previously failed as a silently mis-ordered or un-pickable layer.
• [CHANGE] Layer scaffolds implement only make (plus destroy for a type) and list the rest as commented ops with the default each would replace — an empty setOpacity silently overrides a working core default, so over-implementation is the failure mode worth designing against.
• [ADD] The config/filter/time surfaces documented as contracts in the layertypes README, and the capture surface removed from it (it never existed). Same for the onHostToggle attachment op — no runtime dispatch, and a toggled host already reaches its attachments as setVisibility.
• [CHANGE] Dropped the load op (superseded by the source surface below). It was in LAYER_OPS, the validator, the README table and the scaffold, but core never dispatched it and no type implemented it — data acquisition, including the dynamic-extent refetch on pan/zoom, is core's (Layers_/capture/LayerCapturer), and it is deliberately staying there rather than becoming a per-type op. The op table also omitted render and onToggle, which core does dispatch.
• [CHANGE] One path segment per surface: Vector/map.js, config.js, filter.js, globe/{cesium,lithosphere}.js, non-surface helpers under lib/. The leaf name repeated the plugin directory (Vector/map/vector.js), and globe/config.js — the shared engine-neutral layer descriptor, now globe/layerConfig.js — read as the formal config surface one directory away. Manifest keys are unchanged, since the surface comes from the key and never the path. The dead export defaults in those helpers are gone.
• [CHANGE] create's valid types and the discovery directories were two hand-kept lists, so the help text still advertised five families after layerattachment landed; both now derive from one map.
• [CHANGE] The layertype scaffold shows the phase form ({ before, main, after }, plus afterCommit on make) as a comment beside its bare make. A bare function is sugar for { main: fn }, which made Vector's phase object look like a different contract.
• [FIX] LayerAttachmentRegistry.withOp still read the pre-rename paths.plugin key, so it matched no attachment and clearing a clicked overlay/model silently did nothing. A test now covers both sides of that generated boundary, since a mismatch there fails as a no-op rather than an error.
• [FIX] Destroy a layer's attachments when its host is permanently removed; anything an attachment holds outside a map layer (a globe layer, a DOM element) was leaked.
• [FIX] The specs that regenerate the shared registries (src/pre/*.js, configure/public/*Configs.json — single copies in the repo) now hold a lock across generate-then-assert. A worker running the CLI could otherwise regenerate away a fixture another worker had just written and was asserting on: ~1 run in 3 locally, invisible on CI, which uses one worker.

Four surfaces the authoring experiments asked for

Eight throwaway plugins were written against this branch by separate agents (a globe extrusion renderer, an OGC API Features source, a time-series attachment, an interaction, a backend, a Configure-facing type, …). None had to touch core. What they did hit was core deciding something on their behalf with no way to participate:

• [ADD] layertype source.fetch(layerObj, ctx) -> GeoJSON, dispatched from LayerCapturer on every acquisition (initial make, refresh interval, time requery, dynamic-extent pan). A url string can't express a POST body, auth headers, pagination or an SDK call, so a source that isn't "GET this url" had no home. Core keeps the entire dynamic-extent policy — extent (map or globe), debounce/settling, zoom gate, move threshold (including the /z suffix), request staleness, clear-then-update, reload fan-out — which is why this is not the load op returning: the two duplicated ~150-line branches in captureVector are now one core path plus capture/dynamicExtent.js, and fetch is a pure "given this config and this ctx, give me GeoJSON".

  // ctx: { url, trigger, view, dynamicExtent, crsCode, time, filters, spatialFilter }
  async function fetch(layerObj, ctx) {
      const bbox = ctx.view && [ctx.view.minx, ctx.view.miny, ctx.view.maxx, ctx.view.maxy]
      return await get(layerObj.url, { bbox, ...ctx.time })
  }

• [ADD] layertype legend.derive(layerObj), replacing this, carried in both the LayersTool and the LegendTool (twice, in the second):

  if ((['image', 'tile'].includes(type) && cogTransform) || type === 'velocity' ||
      (type === 'data' && F_.getIn(layer, 'variables.shader.type') === 'colorize'))

  Configured legends (legend url, variables.legend) stay core's. This is for a legend that is the render — a single-band COG's colormap over its rescale range, a shader's ramp, a velocity magnitude scale — which only the type knows it has. Tile, Image, Velocity and Data declare it; derive returning false means "not this layer after all".

• [ADD] attachment onConfigChange(ctx) and mmgisAPI.setLayerAttachmentConfig(layerName, attachmentId, config). Retuning a live attachment (a gradient's ramp, a label's property) had no path at all: core writes the new settings into the host's live config at the attachment's declared configPath — so everything that reads settings, the attachment included, sees them — then dispatches. The default is the blunt but always-correct host rebuild, so declaring the op is an optimization rather than a requirement.

• [ADD] interaction configPath, so an interaction with per-layer settings is handed its own subtree as ctx.config instead of knowing where in layerData it lives — the same declaration attachments already make.

• [ADD] raw (the engine namespace) on both globe contexts, matching mctx.raw on the map. A globe module could reach Cesium/LithoSphere only by importing them itself.

• [FIX] test:plugins:unit failed with "No tests found" whenever no plugin shipped a @unit spec — which is every state of this repo, since the tagged specs only exist in generated plugins.

Issues

• Follows up MeasureTool - Events remain on in Globe when the tool is closed #112.

Testing

• npm run test:unit: 1033 passed (was 967; the new ones cover capability validation, the config.rows metaconfig schema, stale-registry detection, every scaffold generating a plugin that validates, the attachment op lookup below, and the four new surfaces — the dynamic-extent policy source.fetch sits inside is tested directly in tests/unit/layerSource.spec.js: staleness, thresholds, /z scaling, ctx construction). npm run test:ci: passing. npm run plugins -- validate: all 58 plugins valid (1 pre-existing dependency warning for ChemistryUse → ChemistryTool). npm run build and the Configure build: compiled successfully. ESLint on changed files: no new errors (the 7 'L' is not defined in Photosphere.js are pre-existing and unchanged on origin/development).
• Reference Mission verified side-by-side against origin/development (feature on :8889, base on :8891) via scripted browser runs:
  • Same 66/66 layers made, same layer/toggle state, no console errors.
  • Each attachment-bearing layer toggled on and its attachment record dumped (keys, order, sublayerType, child count, globe layer ids): byte-identical output on both branches for uncertainty ellipses, labels, coordinate markers, image overlays, path gradient (2D + 3D) and pairings.
  • getPeerFeatures returns the same paired-layer and peer counts as recomputing from the attachment record directly.