@math.gl/projection 0.0.0-stage → 5.0.0-alpha.12

package/src/experimental/lazy-projections/merc.ts

@@ -0,0 +1,19 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyMercator: ProjectionDescriptor = /* @__PURE__ */ createProjectionDescriptor(
+  {
+    name: 'merc',
+    aliases: [
+      'Mercator',
+      'Popular Visualisation Pseudo Mercator',
+      'Mercator_1SP',
+      'Mercator_Auxiliary_Sphere',
+      'Mercator_Variant_A'
+    ]
+  },
+  async () => (await import('@math.gl/projection/projections/merc')).mercator
+);

package/src/experimental/lazy-projections/mill.ts

@@ -0,0 +1,11 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyMillerCylindrical: ProjectionDescriptor =
+  /* @__PURE__ */ createProjectionDescriptor(
+    {name: 'mill', aliases: ['Miller_Cylindrical']},
+    async () => (await import('@math.gl/projection/projections/mill')).millerCylindrical
+  );

package/src/experimental/lazy-projections/moll.ts

@@ -0,0 +1,10 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyMollweide: ProjectionDescriptor = /* @__PURE__ */ createProjectionDescriptor(
+  {name: 'moll', aliases: ['Mollweide']},
+  async () => (await import('@math.gl/projection/projections/moll')).mollweide
+);

package/src/experimental/lazy-projections/nzmg.ts

@@ -0,0 +1,11 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyNewZealandMapGrid: ProjectionDescriptor =
+  /* @__PURE__ */ createProjectionDescriptor(
+    {name: 'nzmg', aliases: ['New_Zealand_Map_Grid']},
+    async () => (await import('@math.gl/projection/projections/nzmg')).newZealandMapGrid
+  );

package/src/experimental/lazy-projections/ob_tran.ts

@@ -0,0 +1,25 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionPlugin} from '../types';
+
+/** The rotated projection and its child are both deferred until needed. */
+export function lazyObliqueTransformation(
+  wrapped: ProjectionPlugin | ProjectionDescriptor | 'longlat'
+): ProjectionDescriptor {
+  return createProjectionDescriptor(
+    {
+      name: 'ob_tran',
+      aliases: ['General Oblique Transformation', 'General_Oblique_Transformation']
+    },
+    async () => {
+      const [{obliqueTransformation}, child] = await Promise.all([
+        import('@math.gl/projection/projections/ob_tran'),
+        typeof wrapped === 'string' || 'create' in wrapped ? wrapped : wrapped.preload()
+      ]);
+      return obliqueTransformation(child);
+    }
+  );
+}

package/src/experimental/lazy-projections/omerc.ts

@@ -0,0 +1,22 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyObliqueMercator: ProjectionDescriptor = /* @__PURE__ */ createProjectionDescriptor(
+  {
+    name: 'omerc',
+    aliases: [
+      'Hotine_Oblique_Mercator',
+      'Hotine Oblique Mercator',
+      'Hotine_Oblique_Mercator_variant_A',
+      'Hotine_Oblique_Mercator_Variant_B',
+      'Hotine_Oblique_Mercator_Azimuth_Natural_Origin',
+      'Hotine_Oblique_Mercator_Two_Point_Natural_Origin',
+      'Hotine_Oblique_Mercator_Azimuth_Center',
+      'Oblique_Mercator'
+    ]
+  },
+  async () => (await import('@math.gl/projection/projections/omerc')).obliqueMercator
+);

package/src/experimental/lazy-projections/ortho.ts

@@ -0,0 +1,10 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyOrthographic: ProjectionDescriptor = /* @__PURE__ */ createProjectionDescriptor(
+  {name: 'ortho', aliases: []},
+  async () => (await import('@math.gl/projection/projections/ortho')).orthographic
+);

package/src/experimental/lazy-projections/poly.ts

@@ -0,0 +1,10 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyPolyconic: ProjectionDescriptor = /* @__PURE__ */ createProjectionDescriptor(
+  {name: 'poly', aliases: ['Polyconic', 'American_Polyconic']},
+  async () => (await import('@math.gl/projection/projections/poly')).polyconic
+);

package/src/experimental/lazy-projections/qsc.ts

@@ -0,0 +1,14 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyQuadrilateralizedSphericalCube: ProjectionDescriptor =
+  /* @__PURE__ */ createProjectionDescriptor(
+    {
+      name: 'qsc',
+      aliases: ['Quadrilateralized Spherical Cube', 'Quadrilateralized_Spherical_Cube']
+    },
+    async () => (await import('@math.gl/projection/projections/qsc')).quadrilateralizedSphericalCube
+  );

package/src/experimental/lazy-projections/robin.ts

@@ -0,0 +1,10 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyRobinson: ProjectionDescriptor = /* @__PURE__ */ createProjectionDescriptor(
+  {name: 'robin', aliases: ['Robinson']},
+  async () => (await import('@math.gl/projection/projections/robin')).robinson
+);

package/src/experimental/lazy-projections/sinu.ts

@@ -0,0 +1,10 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazySinusoidal: ProjectionDescriptor = /* @__PURE__ */ createProjectionDescriptor(
+  {name: 'sinu', aliases: ['Sinusoidal']},
+  async () => (await import('@math.gl/projection/projections/sinu')).sinusoidal
+);

package/src/experimental/lazy-projections/somerc.ts

@@ -0,0 +1,11 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazySwissObliqueMercator: ProjectionDescriptor =
+  /* @__PURE__ */ createProjectionDescriptor(
+    {name: 'somerc', aliases: []},
+    async () => (await import('@math.gl/projection/projections/somerc')).swissObliqueMercator
+  );

package/src/experimental/lazy-projections/stere.ts

@@ -0,0 +1,18 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyStereographic: ProjectionDescriptor = /* @__PURE__ */ createProjectionDescriptor(
+  {
+    name: 'stere',
+    aliases: [
+      'Stereographic_South_Pole',
+      'Polar_Stereographic_variant_A',
+      'Polar_Stereographic_variant_B',
+      'Polar_Stereographic'
+    ]
+  },
+  async () => (await import('@math.gl/projection/projections/stere')).stereographic
+);

package/src/experimental/lazy-projections/sterea.ts

@@ -0,0 +1,19 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyObliqueStereographic: ProjectionDescriptor =
+  /* @__PURE__ */ createProjectionDescriptor(
+    {
+      name: 'sterea',
+      aliases: [
+        'Stereographic_North_Pole',
+        'Oblique_Stereographic',
+        'Oblique Stereographic Alternative',
+        'Double_Stereographic'
+      ]
+    },
+    async () => (await import('@math.gl/projection/projections/sterea')).obliqueStereographic
+  );

package/src/experimental/lazy-projections/tmerc.ts

@@ -0,0 +1,21 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyTransverseMercator: ProjectionDescriptor =
+  /* @__PURE__ */ createProjectionDescriptor(
+    {
+      name: 'tmerc',
+      aliases: [
+        'Fast_Transverse_Mercator',
+        'Fast Transverse Mercator',
+        'Transverse_Mercator',
+        'Transverse Mercator',
+        'Gauss Kruger',
+        'Gauss_Kruger'
+      ]
+    },
+    async () => (await import('@math.gl/projection/projections/tmerc')).transverseMercator
+  );

package/src/experimental/lazy-projections/tpers.ts

@@ -0,0 +1,11 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyTiltedPerspective: ProjectionDescriptor =
+  /* @__PURE__ */ createProjectionDescriptor(
+    {name: 'tpers', aliases: ['Tilted_Perspective']},
+    async () => (await import('@math.gl/projection/projections/tpers')).tiltedPerspective
+  );

package/src/experimental/lazy-projections/utm.ts

@@ -0,0 +1,11 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyUniversalTransverseMercator: ProjectionDescriptor =
+  /* @__PURE__ */ createProjectionDescriptor(
+    {name: 'utm', aliases: ['Universal Transverse Mercator System']},
+    async () => (await import('@math.gl/projection/projections/utm')).universalTransverseMercator
+  );

package/src/experimental/lazy-projections/vandg.ts

@@ -0,0 +1,10 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Lazy metadata for the projection engine; the algorithm retains its upstream notices.
+import {createProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+export const lazyVanDerGrinten: ProjectionDescriptor = /* @__PURE__ */ createProjectionDescriptor(
+  {name: 'vandg', aliases: ['Van_der_Grinten_I', 'VanDerGrinten', 'Van_der_Grinten']},
+  async () => (await import('@math.gl/projection/projections/vandg')).vanDerGrinten
+);

package/src/experimental/mutable-projection.ts

@@ -0,0 +1,63 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import {ProjectionScratch} from './projection-scratch';
+import type {ProjectionImplementation, ProjectionPoint} from './types';
+
+/** One equation implementation shared by scalar adapters and the mutable pipeline. */
+export function createProjection(
+  forward: (point: ProjectionPoint) => void,
+  inverse: (point: ProjectionPoint) => void
+): ProjectionImplementation {
+  const scratch = new ProjectionScratch();
+  const scalar = (
+    x: number,
+    y: number,
+    operation: (point: ProjectionPoint) => void
+  ): [number, number] => {
+    const point = scratch.acquire();
+    try {
+      point.x = x;
+      point.y = y;
+      point.z = 0;
+      operation(point);
+      return [point.x, point.y];
+    } finally {
+      scratch.release(point);
+    }
+  };
+  return {
+    forward(x, y) {
+      return scalar(x, y, forward);
+    },
+    inverse(x, y) {
+      return scalar(x, y, inverse);
+    },
+    forwardInPlace: forward,
+    inverseInPlace: inverse
+  };
+}
+/** Resolve once at construction. Legacy custom plugins can still allocate their own arrays. */
+export function projectionOperation(
+  implementation: ProjectionImplementation,
+  inverse: boolean,
+  geocentric = false
+): (point: ProjectionPoint) => void {
+  const mutable = inverse ? implementation.inverseInPlace : implementation.forwardInPlace;
+  if (mutable) return mutable.bind(implementation);
+  if (geocentric) {
+    const operation = inverse ? implementation.inverse3D : implementation.forward3D;
+    return point => {
+      const output = operation.call(implementation, [point.x, point.y, point.z]);
+      point.x = output[0];
+      point.y = output[1];
+      point.z = output[2];
+    };
+  }
+  const operation = inverse ? implementation.inverse : implementation.forward;
+  return point => {
+    const output = operation.call(implementation, point.x, point.y);
+    point.x = output[0];
+    point.y = output[1];
+  };
+}

package/src/experimental/numeric-flat.ts

@@ -0,0 +1,73 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original whole-buffer unit/axis pipeline execution with intermediate validation.
+import type {PipelineEpochs} from './projection-pipeline';
+import type {ProjectionArray} from './typescript-projection';
+
+/** Keep multiplication and division distinct, preserving each scalar step's rounding. */
+export type NumericStep = readonly [kind: 0 | 1 | 2, a: number, b: number, c: number];
+export type NumericFlatOperation = (
+  coordinates: ProjectionArray,
+  dimension: number,
+  epochs?: PipelineEpochs
+) => void;
+
+/** Compile only validated unit/axis steps; all other operations retain general dispatch. */
+export function createNumericFlat(steps: readonly NumericStep[]): NumericFlatOperation {
+  const program = new Float64Array(steps.length * 7);
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i],
+      offset = i * 7;
+    program.set(step, offset);
+    if (step[0] === 2) {
+      for (let axis = 1; axis <= 3; axis++) {
+        program[offset + axis] = Math.abs(step[axis]);
+        program[offset + axis + 3] = Math.sign(step[axis]);
+      }
+    }
+  }
+  return (coordinates, dimension, epochs) => {
+    const float32 = coordinates instanceof Float32Array;
+    const epochBuffer = typeof epochs === 'number' ? undefined : epochs;
+    for (let offset = 0, record = 0; offset < coordinates.length; offset += dimension, record++) {
+      let x = coordinates[offset],
+        y = coordinates[offset + 1],
+        z = dimension >= 3 ? coordinates[offset + 2] : 0;
+      if (epochBuffer && !Number.isFinite(epochBuffer[record]))
+        throw new Error('Coordinate epoch must be a finite decimal year');
+      if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+        throw new Error('Pipeline coordinate must be finite');
+      for (let step = 0; step < program.length; step += 7) {
+        const kind = program[step],
+          a = program[step + 1],
+          b = program[step + 2],
+          c = program[step + 3];
+        if (kind === 0) {
+          x *= a;
+          y *= b;
+          z *= c;
+        } else if (kind === 1) {
+          x /= a;
+          y /= b;
+          z /= c;
+        } else {
+          const oldX = x,
+            oldY = y,
+            oldZ = z;
+          x = program[step + 4] * (a === 1 ? oldX : a === 2 ? oldY : oldZ);
+          y = program[step + 5] * (b === 1 ? oldX : b === 2 ? oldY : oldZ);
+          z = program[step + 6] * (c === 1 ? oldX : c === 2 ? oldY : oldZ);
+        }
+        // An overflowing intermediate must fail even if a later conversion would cancel it.
+        if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+          throw new Error('Pipeline coordinate must be finite');
+      }
+      if (float32 && Math.max(Math.abs(x), Math.abs(y), Math.abs(z)) > 3.4028234663852886e38)
+        throw new Error('Pipeline output exceeds Float32 range');
+      coordinates[offset] = x;
+      coordinates[offset + 1] = y;
+      if (dimension >= 3) coordinates[offset + 2] = z;
+    }
+  };
+}

package/src/experimental/parameters.ts

@@ -0,0 +1,35 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ProjectionParameters} from './types';
+
+export const DEGREES_TO_RADIANS = Math.PI / 180;
+
+/** Read a finite decimal parameter, rejecting flags, empty values and other syntaxes. */
+export function numberParameter(
+  parameters: ProjectionParameters,
+  name: string,
+  fallback: number
+): number {
+  if (!Object.prototype.hasOwnProperty.call(parameters, name)) return fallback;
+  const value = parameters[name];
+  if (typeof value !== 'string' || !/^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(value)) {
+    throw new Error(`Invalid numeric PROJ parameter: +${name}`);
+  }
+  const number = Number(value);
+  if (!Number.isFinite(number)) throw new Error(`Invalid numeric PROJ parameter: +${name}`);
+  return number;
+}
+
+export function latitudeParameter(parameters: ProjectionParameters, name: string): number {
+  const degrees = numberParameter(parameters, name, 0);
+  if (Math.abs(degrees) >= 90) throw new Error(`+${name} must be between -90 and 90 degrees`);
+  return degrees * DEGREES_TO_RADIANS;
+}
+
+export function wrapLongitude(longitude: number): number {
+  if (Math.abs(longitude) <= Math.PI) return longitude;
+  const circle = 2 * Math.PI;
+  return ((((longitude + Math.PI) % circle) + circle) % circle) - Math.PI;
+}

package/src/experimental/projection-descriptor.ts

@@ -0,0 +1,79 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original descriptor/cache implementation, following loaders.gl's distinction between lightweight metadata and cached runtime implementations.
+import type {ProjectionPlugin} from './types';
+
+export type ProjectionDescriptor = {
+  readonly name: string;
+  readonly aliases?: readonly string[];
+  preload(): Promise<ProjectionPlugin>;
+};
+type LoadedProjection = {
+  load: () => Promise<ProjectionPlugin>;
+  pending?: Promise<ProjectionPlugin>;
+  implementation?: ProjectionPlugin;
+};
+// CJS entry points are separately bundled. Share a weak, identity-keyed cache
+// across them without conflating descriptors that have the same projection name.
+const CACHE_KEY = Symbol.for('@math.gl/projection/projection-implementations');
+function cache(): WeakMap<ProjectionDescriptor, LoadedProjection> {
+  const scope = globalThis as typeof globalThis & {
+    [CACHE_KEY]?: WeakMap<ProjectionDescriptor, LoadedProjection>;
+  };
+  scope[CACHE_KEY] ||= new WeakMap();
+  return scope[CACHE_KEY];
+}
+
+/** Return an eager or previously loaded implementation without starting an import. */
+export function getLoadedProjection(
+  projection: ProjectionPlugin | ProjectionDescriptor
+): ProjectionPlugin | undefined {
+  return 'create' in projection ? projection : cache().get(projection)?.implementation;
+}
+
+/** Resolve and cache an implementation; concurrent requests share the same import. */
+export function preloadProjection(
+  projection: ProjectionPlugin | ProjectionDescriptor
+): Promise<ProjectionPlugin> {
+  if ('create' in projection) return Promise.resolve(projection);
+  let state = cache().get(projection);
+  if (!state) {
+    state = {load: () => projection.preload()};
+    cache().set(projection, state);
+  }
+  if (state.implementation) return Promise.resolve(state.implementation);
+  const entry = state;
+  entry.pending ||= Promise.resolve()
+    .then(entry.load)
+    .then(plugin => {
+      const key = (value: string) => value.toLowerCase().replace(/[\s_-]/g, '');
+      const supported = new Set([plugin.name, ...(plugin.aliases || [])].map(key));
+      if (
+        typeof plugin.create !== 'function' ||
+        ![projection.name, ...(projection.aliases || [])].every(name => supported.has(key(name)))
+      )
+        throw new Error('Loaded projection does not match descriptor: ' + projection.name);
+      entry.implementation = plugin;
+      return plugin;
+    })
+    .catch(error => {
+      entry.pending = undefined;
+      throw error;
+    });
+  return entry.pending;
+}
+
+/** Create a lightweight descriptor whose preload() populates the shared cache. */
+export function createProjectionDescriptor(
+  metadata: Pick<ProjectionPlugin, 'name' | 'aliases'>,
+  load: () => Promise<ProjectionPlugin>
+): ProjectionDescriptor {
+  const descriptor: ProjectionDescriptor = Object.freeze({
+    name: metadata.name,
+    aliases: metadata.aliases && Object.freeze([...metadata.aliases]),
+    preload: () => preloadProjection(descriptor)
+  });
+  cache().set(descriptor, {load});
+  return descriptor;
+}