starmaking-engine

Point detection and vector text snapping for constellation drawings. Framework-independent ESM with TypeScript declarations. MIT licensed.

npm install starmaking-engine

Compose text

import { preparePoints, composeText } from "starmaking-engine";

const stars = Array.from({ length: 2400 }, (_, i) => ({
  x: (i % 60) * 16, y: Math.floor(i / 60) * 16, brightness: 255,
}));
const prepared = preparePoints(stars);
const entry = {
  id: "title", message: "HELLO", fontSize: 62, textPadding: 0,
  tracking: 0.22, lineSpacing: 1.35, textAlign: "left", rotation: 0,
  quad: {
    topLeft: { x: 50, y: 50 }, topRight: { x: 450, y: 50 },
    bottomRight: { x: 450, y: 250 }, bottomLeft: { x: 50, y: 250 },
  },
};
const settings = { strokeWidth: 1.8, showStarPoints: false,
  snapRadiusScale: 1, pathDensity: 1, bridgeGaps: true };
const size = { width: 980, height: 620 };
const result = composeText(prepared, { textEntries: [entry], overlayControls: settings }, size);
const moved = composeText(prepared, {
  textEntries: [{ ...entry, rotation: 20 }], overlayControls: settings,
}, size);
// result.polylines and moved.polylines can be drawn with any renderer.

Each call immediately computes new snapping. There is no clock, playback state, interpolation, randomness, or alternate-solution selection. Hosts can change placement or snapping parameters at their own cadence.

Entry points

• starmaking-engine: detectStars, toLuminanceBuffer, projectCatalogStars, layoutTextSegments, textSegmentsForEntry, segmentsToConstellationPolylines, preparePoints, composeText, geometry helpers, and readonly domain types.
• starmaking-engine/browser: prepareRenderScene, composeOverlayResult, composeRenderScene, Canvas drawing, image conversion, and palette helpers. These adapters use browser APIs; decoding images and scheduling workers belong to the host.
• starmaking-engine/svg: renderResultToSvg, renderLineworkSvg, and renderAlignmentSvg. SVG serialization accepts geometry without a browser.

detectStars accepts { data: Uint8ClampedArray, width, height } in RGBA order. Transparent pixels are composited over black. Keep pixel buffers and star arrays immutable: analysis is cached by buffer identity and spatial indexes by array identity. Replace the object/array when its content changes. Detection preserves brightness-prioritized spacing suppression and eight-connected components.

Coordinates, quads, and returned polylines use the supplied layout's units. Rotation is in degrees. For compatibility, font sizes and snapping reach scale by min(width / 980, height / 620). Tracking and line spacing are ratios; padding is a fraction of the text box (clamped to 0–0.45). Quads must be convex. Empty point sets produce no paths. Layout dimensions must be positive finite numbers.

Default snapping: radius multiplier 1, density 1, gap bridging enabled. Radius is clamped to 0.1–3 and density to 0.25–4. The nearest point wins; this is not a random solver. Stroke width and point visibility affect presentation, not geometry. For exports, scale the finished composition to avoid changing its topology.

Catalog projection accepts RA/Dec in degrees and returns layout coordinates. Catalog downloads, image assets, saved-project formats, and editor controls are not included. The browser adapter's layer selection determines the threshold background; visible layers contribute deduplicated snapping points.

Development and releases

Use Node 22 or newer. Run npm ci, npm run typecheck, npm test, npm run build, and npm run test:package. CI runs these checks on pull requests and main. Package checks install a tarball into an isolated consumer and compile its imports without repository aliases.

Stable releases use tags vX.Y.Z matching package.json. Commit a version bump and lockfile update, push the commit/tag, wait for CI, then publish a GitHub release for the tag. The release workflow repeats all checks before publishing through npm OIDC, with provenance. It rejects prerelease versions and mismatched tags.

Bootstrap the first package from a tested local tarball using npm login/2FA. Then run npm trust github starmaking-engine --repo dzucconi/starmaking-engine --file publish.yml --allow-publish (on one line) with npm >=11.15 and 2FA enabled. Subsequent releases need no npm token secret. The package repository URL must continue matching the trusted GitHub repository.