mudlet-map-renderer 1.0.0 → 1.2.0

package/dist/ScenePipeline.d.ts

@@ -0,0 +1,226 @@
+import { IMapReader } from './reader/MapReader';
+import { IArea } from './reader/Area';
+import { IPlane } from './reader/Plane';
+import { Settings } from './types/Settings';
+import { default as ExitRenderer, ExitDrawData } from './ExitRenderer';
+import { GroupShape, Shape } from './scene/Shape';
+import { RoomLens } from './lens/RoomLens';
+type Bounds = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Reference to one room's body shape inside the scene. Keyed by roomId so
+ * downstream consumers (cull index, hit-test bookkeeping) can find a room
+ * shape by id without re-walking the scene tree.
+ */
+export type RoomShapeRef = {
+    room: MapData.Room;
+    shape: GroupShape;
+};
+/**
+ * Reference to one drawn link-exit shape, paired with its world-space bounds
+ * and (optional) cross-area target room. Used by the live renderer to hang
+ * cull entries on each exit.
+ */
+export type StandaloneExitShapeRef = {
+    shape: GroupShape;
+    bounds: Bounds;
+    targetRoomId?: number;
+};
+export type AreaExitHitZone = {
+    bounds: Bounds;
+    targetRoomId: number;
+    /** Source room center — used to compute arrow direction for labels. Optional for back-compat. */
+    from?: {
+        x: number;
+        y: number;
+    };
+    /** Arrow tip / far endpoint — anchor for placed labels. Optional for back-compat. */
+    tip?: {
+        x: number;
+        y: number;
+    };
+    /** Stroke colour of the rendered arrow — used to colour area-exit labels. */
+    arrowColor?: string;
+};
+/**
+ * One drawn two-way or one-way inter-room exit, with stable identity and the
+ * exact geometry ExitRenderer produced. Consumers (e.g. an editor's
+ * hit-testing layer) can run segment distance checks against
+ * `data.lines[].points` / `data.arrows[].points` to match exactly what the
+ * user sees — including dash patterns and the renderer's suppression rules
+ * (e.g. both-sides-customLine two-ways, one-ways overridden by customLine).
+ */
+export type DrawnExitEntry = {
+    readonly a: number;
+    readonly b: number;
+    readonly aDir?: MapData.direction;
+    readonly bDir?: MapData.direction;
+    readonly kind: "exit" | "specialExit";
+    readonly zIndex: number[];
+    readonly data: ExitDrawData;
+};
+/**
+ * One drawn custom-line (special exit) polyline, as it was rendered for
+ * this scene. `points` is the flat [x,y,x,y,...] polyline with the source
+ * room's centre prepended (mirroring what the renderer actually drew), in
+ * render-space coordinates.
+ */
+export type DrawnSpecialExitEntry = {
+    readonly roomId: number;
+    readonly exitName: string;
+    readonly points: number[];
+    readonly stroke: string;
+    readonly strokeWidth: number;
+    readonly dash?: number[];
+    readonly hasArrow: boolean;
+    readonly arrowTip?: {
+        x: number;
+        y: number;
+    };
+    readonly bounds: Bounds;
+};
+/**
+ * One drawn stub — a room's one-way exit indicator (the short line sticking
+ * out of the edge for every entry in `room.stubs`). Rendered directly from
+ * these coordinates by {@link ScenePipeline}, so hit-testing against them
+ * matches what's on screen. Non-planar stubs (up/down/in/out) are still
+ * recorded — x1==x2 and y1==y2 — so consumers can filter them out.
+ */
+export type DrawnStubEntry = {
+    readonly roomId: number;
+    readonly direction: MapData.direction;
+    readonly x1: number;
+    readonly y1: number;
+    readonly x2: number;
+    readonly y2: number;
+    readonly stroke: string;
+    readonly strokeWidth: number;
+};
+/**
+ * World-space shapes for each logical layer. Same content the backend layer
+ * nodes received, but as plain SceneIR data — consumed by exporters that drive
+ * {@link buildDrawCommands} → engine renderers without going through a
+ * {@link DrawingBackend}.
+ *
+ * Order within each list mirrors the order in which the corresponding layer
+ * node received its `addNode` calls: e.g. `link` is labels → link exits → for
+ * each room (special exits, stubs); `room` is rooms → area name → area-exit
+ * labels.
+ */
+export type SceneShapesByLayer = {
+    grid: Shape[];
+    link: Shape[];
+    room: Shape[];
+    topLabel: Shape[];
+};
+/** User-defined label shape paired with its world-space bounds (for culling). */
+export type LabelShapeRef = {
+    shape: GroupShape;
+    bounds: Bounds;
+};
+/** Custom-line (special-exit) shape paired with its world-space bounds (for culling). */
+export type SpecialExitShapeRef = {
+    shape: GroupShape;
+    bounds: Bounds;
+};
+/** Stub shape paired with its world-space bounds (for culling). */
+export type StubShapeRef = {
+    shape: GroupShape;
+    bounds: Bounds;
+};
+/** Area-exit label shape paired with its world-space bounds (for culling). */
+export type AreaExitLabelShapeRef = {
+    shape: GroupShape;
+    bounds: Bounds;
+};
+export type SceneBuildResult = {
+    /** Room body shapes keyed by roomId — for cull-entry construction. */
+    roomShapeRefs: Map<number, RoomShapeRef>;
+    /** Link-exit shapes paired with bounds and area-target metadata. */
+    standaloneExitShapeRefs: StandaloneExitShapeRef[];
+    /** Non-noScaling label shapes paired with world-space bounds (for culling). */
+    labelShapeRefs: LabelShapeRef[];
+    /** Custom-line special-exit shapes paired with world-space bounds (for culling). */
+    specialExitShapeRefs: SpecialExitShapeRef[];
+    /** Stub shapes paired with world-space bounds (for culling). */
+    stubShapeRefs: StubShapeRef[];
+    /** Area-exit label shapes paired with world-space bounds (for culling). */
+    areaExitLabelShapeRefs: AreaExitLabelShapeRef[];
+    areaExitHitZones: AreaExitHitZone[];
+    drawnExits: DrawnExitEntry[];
+    drawnSpecialExits: DrawnSpecialExitEntry[];
+    drawnStubs: DrawnStubEntry[];
+    /** World-space shapes carrying {@link HitInfo} annotations — fed to {@link HitTester}. */
+    hitShapes: Shape[];
+    /**
+     * Engine-agnostic shape lists per logical layer. Drives
+     * {@link buildDrawCommands} + a per-engine renderer.
+     */
+    sceneShapes: SceneShapesByLayer;
+};
+/**
+ * Engine-neutral scene composition pipeline.
+ *
+ * Walks a {@link MapData} area/plane and emits world-space {@link Shape}s per
+ * logical layer (grid / link / room / topLabel) plus the metadata downstream
+ * consumers need (cull entries, hit zones, drawn-geometry snapshots).
+ *
+ * The pipeline knows nothing about Konva, SVG, Canvas, or the
+ * {@link DrawCommandBuilder}: callers run the shape lists through whatever
+ * renderer fits their target. Both the interactive
+ * {@link KonvaRenderBackend} and the exporters consume the same
+ * {@link SceneBuildResult} this pipeline produces.
+ */
+export declare class ScenePipeline {
+    private readonly mapReader;
+    private readonly settings;
+    readonly exitRenderer: ExitRenderer;
+    private linkShapes;
+    private roomShapes;
+    private topLabelShapes;
+    private labelShapeRefs;
+    private specialExitShapeRefs;
+    private stubShapeRefs;
+    private areaExitLabelShapeRefs;
+    constructor(mapReader: IMapReader, settings: Settings);
+    /**
+     * Build the full scene for an area/plane.
+     * Clears layers, renders grid → labels → exits → rooms → area name.
+     * Returns data for culling and interaction (room nodes, exit data, hit zones).
+     *
+     * The `lens` filters which rooms paint and how partially-visible exits are
+     * treated. Pass {@link ALL_VISIBLE} (or omit) for an unfiltered build.
+     */
+    buildScene(area: IArea, plane: IPlane, zIndex: number, lens?: RoomLens): SceneBuildResult;
+    getEffectiveBounds(area: IArea, plane: IPlane): {
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    };
+    private renderRooms;
+    private renderLinkExits;
+    /**
+     * Build a stub anchored at the visible endpoint of an exit, pointing
+     * toward the hidden one. Returns undefined when the exit can't be drawn
+     * as a stub (no planar direction on the visible side, both sides hidden,
+     * or both sides visible — the last is a caller bug).
+     */
+    private buildLensStub;
+    private emitLensStub;
+    private getRoomEdgePoint;
+    /**
+     * Build the world-space shape tree for one inter-room exit. Used by the
+     * live renderer's current-room overlay path to recolour a single exit
+     * without rebuilding the whole scene.
+     */
+    buildExitShape(data: ExitDrawData): GroupShape;
+    private renderLabels;
+    private renderAreaExitLabels;
+    private renderAreaName;
+}
+export {};

package/dist/SvgTypes.d.ts

@@ -0,0 +1,21 @@
+export type SvgOverlays = {
+    position?: {
+        roomId: number;
+    };
+    highlights?: Array<{
+        roomId: number;
+        color: string;
+    }>;
+    paths?: Array<{
+        locations: number[];
+        color: string;
+    }>;
+};
+export type SvgExportOptions = {
+    /** Room ID to center the export on. If omitted, exports the full area. */
+    roomId?: number;
+    /** Padding in map units around the exported region. Default: 3 */
+    padding?: number;
+    /** Overlay data (position marker, highlights, paths) to include in the export. */
+    overlays?: SvgOverlays;
+};

package/dist/TypedEventEmitter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Lightweight typed event emitter.
+ * Also dispatches DOM CustomEvents on an optional container element
+ * for backwards compatibility.
+ */
+export declare class TypedEventEmitter<EventMap extends Record<string, unknown>> {
+    private listeners;
+    private container?;
+    /**
+     * @param container Optional DOM element to also dispatch CustomEvents on (for backwards compat)
+     */
+    constructor(container?: HTMLElement);
+    on<K extends keyof EventMap>(event: K, handler: (detail: EventMap[K]) => void): void;
+    off<K extends keyof EventMap>(event: K, handler: (detail: EventMap[K]) => void): void;
+    removeAllListeners(): void;
+    emit<K extends keyof EventMap>(event: K, detail: EventMap[K]): void;
+}

package/dist/binary/BinaryMapReader.d.ts

@@ -0,0 +1,36 @@
+import { MudletMap, readMapFromBuffer } from 'mudlet-map-binary-reader';
+import { IMapReader } from '../reader/MapReader';
+import { IArea } from '../reader/Area';
+/**
+ * {@link IMapReader} implementation backed by a parsed Mudlet binary map.
+ *
+ * Convenience wrapper around the existing {@link MapReader} that converts a
+ * {@link MudletMap} (the in-memory binary model from
+ * `mudlet-map-binary-reader`) into the renderer's `{mapData, colors}` shape
+ * via `readerExport()`, then forwards every `IMapReader` call to the wrapped
+ * reader.
+ *
+ * Useful for downstream apps (the upstream Mudix client is one) that already
+ * own binary `.dat` bytes and want a single object they can hand to
+ * {@link MapRenderer} without staging a separate JSON export step.
+ *
+ * `mudlet-map-binary-reader` is a `peerDependency`; consumers who do not use
+ * binary maps never pay the bundle cost.
+ */
+export default class BinaryMapReader implements IMapReader {
+    private readonly reader;
+    /** Build directly from a parsed {@link MudletMap}. */
+    constructor(model: MudletMap);
+    /**
+     * Parse the given binary map buffer and construct a reader from it.
+     * In Node, pass `fs.readFileSync(path)`; in the browser, construct a
+     * `Buffer` from an `ArrayBuffer` (e.g. via the `buffer` polyfill).
+     */
+    static fromBuffer(buf: Parameters<typeof readMapFromBuffer>[0]): BinaryMapReader;
+    getArea(areaId: number): IArea;
+    getAreas(): IArea[];
+    getRooms(): MapData.Room[];
+    getRoom(roomId: number): MapData.Room;
+    getColorValue(envId: number): string;
+    getSymbolColor(envId: number, opacity?: number): string;
+}

package/dist/binary/index.d.ts

@@ -0,0 +1,2 @@
+export { default as BinaryMapReader } from './BinaryMapReader';
+export type { MudletMap, MudletArea, MudletRoom, MudletColor, MudletLabel } from 'mudlet-map-binary-reader';

package/dist/binary.mjs

@@ -0,0 +1,34 @@
+import { t as e } from "./MapReader-mU_4JWv_.js";
+import { readMapFromBuffer as t, readerExport as n } from "mudlet-map-binary-reader";
+//#region src/binary/BinaryMapReader.ts
+var r = class r {
+	constructor(t) {
+		let { mapData: r, colors: i } = n(t);
+		this.reader = new e(r, i);
+	}
+	static fromBuffer(e) {
+		return new r(t(e));
+	}
+	getArea(e) {
+		return this.reader.getArea(e);
+	}
+	getAreas() {
+		return this.reader.getAreas();
+	}
+	getRooms() {
+		return this.reader.getRooms();
+	}
+	getRoom(e) {
+		return this.reader.getRoom(e);
+	}
+	getColorValue(e) {
+		return this.reader.getColorValue(e);
+	}
+	getSymbolColor(e, t) {
+		return this.reader.getSymbolColor(e, t);
+	}
+};
+//#endregion
+export { r as BinaryMapReader };
+
+//# sourceMappingURL=binary.mjs.map

package/dist/binary.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary.mjs","names":[],"sources":["../src/binary/BinaryMapReader.ts"],"sourcesContent":["import {\n    type MudletMap,\n    readerExport,\n    readMapFromBuffer,\n} from \"mudlet-map-binary-reader\";\nimport MapReader, {type IMapReader} from \"../reader/MapReader\";\nimport type {IArea} from \"../reader/Area\";\n\n/**\n * {@link IMapReader} implementation backed by a parsed Mudlet binary map.\n *\n * Convenience wrapper around the existing {@link MapReader} that converts a\n * {@link MudletMap} (the in-memory binary model from\n * `mudlet-map-binary-reader`) into the renderer's `{mapData, colors}` shape\n * via `readerExport()`, then forwards every `IMapReader` call to the wrapped\n * reader.\n *\n * Useful for downstream apps (the upstream Mudix client is one) that already\n * own binary `.dat` bytes and want a single object they can hand to\n * {@link MapRenderer} without staging a separate JSON export step.\n *\n * `mudlet-map-binary-reader` is a `peerDependency`; consumers who do not use\n * binary maps never pay the bundle cost.\n */\nexport default class BinaryMapReader implements IMapReader {\n    private readonly reader: MapReader;\n\n    /** Build directly from a parsed {@link MudletMap}. */\n    constructor(model: MudletMap) {\n        const {mapData, colors} = readerExport(model);\n        // RendererRoom (binary-reader output) and MapData.Room (renderer\n        // input) overlap structurally — RendererRoom is missing only\n        // `areaId`, which the renderer never reads from rooms (only from\n        // the area). Cast through `unknown` to bridge the nominal gap.\n        this.reader = new MapReader(mapData as unknown as MapData.Map, colors);\n    }\n\n    /**\n     * Parse the given binary map buffer and construct a reader from it.\n     * In Node, pass `fs.readFileSync(path)`; in the browser, construct a\n     * `Buffer` from an `ArrayBuffer` (e.g. via the `buffer` polyfill).\n     */\n    static fromBuffer(buf: Parameters<typeof readMapFromBuffer>[0]): BinaryMapReader {\n        return new BinaryMapReader(readMapFromBuffer(buf));\n    }\n\n    // --- IMapReader forwarding ---\n\n    getArea(areaId: number): IArea {\n        return this.reader.getArea(areaId);\n    }\n\n    getAreas(): IArea[] {\n        return this.reader.getAreas();\n    }\n\n    getRooms(): MapData.Room[] {\n        return this.reader.getRooms();\n    }\n\n    getRoom(roomId: number): MapData.Room {\n        return this.reader.getRoom(roomId);\n    }\n\n    getColorValue(envId: number): string {\n        return this.reader.getColorValue(envId);\n    }\n\n    getSymbolColor(envId: number, opacity?: number): string {\n        return this.reader.getSymbolColor(envId, opacity);\n    }\n}\n"],"mappings":";;;AAwBA,IAAqB,IAArB,MAAqB,EAAsC;CAIvD,YAAY,GAAkB;EAC1B,IAAM,EAAC,YAAS,cAAU,EAAa,EAAM;AAK7C,OAAK,SAAS,IAAI,EAAU,GAAmC,EAAO;;CAQ1E,OAAO,WAAW,GAA+D;AAC7E,SAAO,IAAI,EAAgB,EAAkB,EAAI,CAAC;;CAKtD,QAAQ,GAAuB;AAC3B,SAAO,KAAK,OAAO,QAAQ,EAAO;;CAGtC,WAAoB;AAChB,SAAO,KAAK,OAAO,UAAU;;CAGjC,WAA2B;AACvB,SAAO,KAAK,OAAO,UAAU;;CAGjC,QAAQ,GAA8B;AAClC,SAAO,KAAK,OAAO,QAAQ,EAAO;;CAGtC,cAAc,GAAuB;AACjC,SAAO,KAAK,OAAO,cAAc,EAAM;;CAG3C,eAAe,GAAe,GAA0B;AACpD,SAAO,KAAK,OAAO,eAAe,GAAO,EAAQ"}

package/dist/camera/Camera.d.ts

@@ -0,0 +1,118 @@
+import { ViewportBounds } from '../types/Settings';
+import { TypedEventEmitter } from '../TypedEventEmitter';
+/** Pixels-per-world-unit at zoom = 1. Multiply by `Camera.zoom` for actual scale. */
+export declare const BASE_SCALE = 75;
+/** Events fired by {@link Camera}. */
+export type CameraEventMap = {
+    /** Any state change: zoom, pan, size, animation tick. */
+    change: void;
+};
+/**
+ * Engine-agnostic camera — owns transform state, drag, and animation.
+ *
+ * Subscribers ({@link KonvaRenderer}, {@link CullingManager}, {@link HitTester},
+ * scene overlays) listen to the `change` event to react to view updates.
+ *
+ * No Konva, no DOM. Only dependency is requestAnimationFrame (with a
+ * setTimeout fallback for Node.js).
+ */
+export declare class Camera extends TypedEventEmitter<CameraEventMap> {
+    zoom: number;
+    minZoom: number;
+    position: {
+        x: number;
+        y: number;
+    };
+    width: number;
+    height: number;
+    /** When true, resizing re-centers on the last panToMapPoint target. */
+    centerOnResize: boolean;
+    private dragging;
+    private dragStart;
+    private positionAtDragStart;
+    private animationId?;
+    private batchDepth;
+    private batchDirty;
+    constructor(width: number, height: number);
+    getScale(): number;
+    setZoom(zoom: number): boolean;
+    /** Zoom keeping the center of the viewport fixed. */
+    zoomToCenter(zoom: number): boolean;
+    /** Zoom keeping a specific screen point fixed (for mouse wheel zoom). */
+    zoomToPoint(zoom: number, screenX: number, screenY: number): boolean;
+    /** Bounds of the visible area in map space. */
+    getViewportBounds(): ViewportBounds;
+    /**
+     * Map-space bounds to use for culling. When `cullingBounds` is a
+     * screen-pixel sub-rect it is converted to map space via the current
+     * camera transform; otherwise the full viewport is returned.
+     */
+    getCullingViewport(cullingBounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null): ViewportBounds;
+    /**
+     * Create a Camera whose full viewport covers exactly the given world-space bounds.
+     * Used by headless exporters that need a Camera but have no real display.
+     */
+    static forMapBounds(minX: number, maxX: number, minY: number, maxY: number): Camera;
+    /**
+     * Create a Camera from an explicit render-camera transform (scale + offset).
+     * Used by {@link CanvasExporter} to derive culling bounds from the already-
+     * computed fitted transform without re-doing the letterbox math.
+     */
+    static forRenderCamera(width: number, height: number, scale: number, offsetX: number, offsetY: number): Camera;
+    /** Convert client/screen coordinates to map coordinates. */
+    clientToMapPoint(clientX: number, clientY: number, containerOffset?: {
+        left: number;
+        top: number;
+    }): {
+        x: number;
+        y: number;
+    } | null;
+    /** Center on a map coordinate, instantly. */
+    panToMapPoint(x: number, y: number): void;
+    /** Center on a map coordinate, with optional animation. */
+    panToMapPointAnimated(x: number, y: number, instant: boolean): void;
+    /**
+     * Compute the zoom level that would fit the given map bounds in the current
+     * viewport (with the same padding/insets as {@link fitToMapBounds}).
+     */
+    computeFitZoom(minX: number, maxX: number, minY: number, maxY: number, insets?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    }): number;
+    /**
+     * Fit the camera to show the given map bounds with padding.
+     * Optional `insets` (screen pixels) reserve space at each edge.
+     */
+    fitToMapBounds(minX: number, maxX: number, minY: number, maxY: number, insets?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    }): void;
+    setSize(width: number, height: number): void;
+    startDrag(screenX: number, screenY: number): void;
+    updateDrag(screenX: number, screenY: number): void;
+    endDrag(): void;
+    isDragging(): boolean;
+    private animate;
+    cancelAnimation(): void;
+    isAnimating(): boolean;
+    /**
+     * Run a function that performs multiple camera mutations and emit only one
+     * `change` event at the end (if anything actually mutated). Use this when a
+     * single logical operation needs to touch more than one camera field —
+     * resize-then-recenter, for example — so subscribers never observe a
+     * transient inconsistent state (new size with stale position).
+     *
+     * Nested batches are supported: only the outermost batch emits.
+     */
+    batch<T>(fn: () => T): T;
+    private notify;
+}

package/dist/coord/CoordFn.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Forward / inverse 2D coordinate transform. Used by camera-aware code that
+ * needs to translate between world space (the map's flat XY) and scene space
+ * (whatever the active style projects into — e.g. an isometric diamond).
+ *
+ * `IDENTITY_TRANSFORM` returns the input unchanged; flat styles (Parchment,
+ * Sketchy, plain identity) use it for both the forward and inverse direction.
+ */
+export type CoordFn = (x: number, y: number) => {
+    x: number;
+    y: number;
+};
+export declare const IDENTITY_TRANSFORM: CoordFn;

package/dist/directions.d.ts

@@ -0,0 +1,25 @@
+export type PlanarDirection = "north" | "south" | "east" | "west" | "northeast" | "northwest" | "southeast" | "southwest";
+export declare const planarDirections: PlanarDirection[];
+export declare const oppositeDirections: Record<PlanarDirection, PlanarDirection>;
+export declare function movePoint(x: number, y: number, direction?: MapData.direction, distance?: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Calculate the edge point of a rounded rectangle for a given direction.
+ * Cardinal directions use the flat edge (same as rectangle).
+ * Diagonal directions intersect the corner arc.
+ */
+export declare function movePointRoundedRect(x: number, y: number, direction?: MapData.direction, distance?: number, cornerRadius?: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Calculate the edge point of a circle for a given direction
+ * For circles, we need to calculate the exact point on the circle's circumference
+ * based on the angle to the direction
+ */
+export declare function movePointCircle(x: number, y: number, direction?: MapData.direction, radius?: number): {
+    x: number;
+    y: number;
+};

package/dist/draw/DrawCommand.d.ts

@@ -0,0 +1,104 @@
+import { LayerId } from '../scene/Shape';
+export interface RectCommand {
+    type: "rect";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    fill?: string;
+    stroke?: string;
+    /** Stroke width in render units. */
+    sw: number;
+    /** Corner radius in render units. */
+    cr: number;
+    dash?: number[];
+}
+export interface CircleCommand {
+    type: "circle";
+    cx: number;
+    cy: number;
+    r: number;
+    fill?: string;
+    stroke?: string;
+    sw: number;
+    dash?: number[];
+}
+export interface LineCommand {
+    type: "line";
+    /** Flat list of [x0, y0, x1, y1, …] in render space. */
+    points: number[];
+    stroke?: string;
+    sw: number;
+    dash?: number[];
+    lineCap?: "butt" | "round" | "square";
+    lineJoin?: "miter" | "round" | "bevel";
+    /** 0..1 multiplier. */
+    alpha?: number;
+}
+export interface PolygonCommand {
+    type: "polygon";
+    vertices: number[];
+    fill?: string;
+    stroke?: string;
+    sw: number;
+}
+export interface TextCommand {
+    type: "text";
+    x: number;
+    y: number;
+    text: string;
+    fontSize: number;
+    fontFamily: string;
+    fontStyle: string;
+    fill: string;
+    stroke?: string;
+    /** Stroke width in render units (0 = no stroke). */
+    sw: number;
+    align: "left" | "center" | "right";
+    vAlign: "top" | "middle" | "bottom";
+    w: number;
+    h: number;
+    baselineRatio?: number;
+    konvaCorrectionRatio?: number;
+    transform?: [number, number, number, number, number, number];
+}
+export interface ImageCommand {
+    type: "image";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    src: string;
+    transform?: [number, number, number, number, number, number];
+}
+/** Push an affine transform [a, b, c, d, e, f] onto the renderer's stack. */
+export interface PushTransformCommand {
+    type: "pushTransform";
+    matrix: [number, number, number, number, number, number];
+}
+/** Pop the most recent transform. */
+export interface PopTransformCommand {
+    type: "popTransform";
+}
+/** Push a clip rect; subsequent draws are clipped until matching pop. */
+export interface PushClipCommand {
+    type: "pushClip";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface PopClipCommand {
+    type: "popClip";
+}
+export type PrimitiveDrawCommand = RectCommand | CircleCommand | LineCommand | PolygonCommand | TextCommand | ImageCommand;
+export type StackDrawCommand = PushTransformCommand | PopTransformCommand | PushClipCommand | PopClipCommand;
+export type DrawCommand = PrimitiveDrawCommand | StackDrawCommand;
+/**
+ * A bundle of commands targeting one logical layer. Renderers iterate layers
+ * in z-order and flush commands per layer.
+ */
+export interface DrawCommandBatch {
+    layer: LayerId;
+    commands: DrawCommand[];
+}

package/dist/draw/DrawCommandBuilder.d.ts

@@ -0,0 +1,19 @@
+import { DrawCommandBatch } from './DrawCommand';
+import { Shape } from '../scene/Shape';
+/** Camera state needed to project world coordinates into render space. */
+export interface CameraTransform {
+    /** Pixels per world unit. */
+    scale: number;
+    /** Render-space origin in pixels. */
+    offsetX: number;
+    offsetY: number;
+}
+/**
+ * Build per-layer {@link DrawCommandBatch}es from a list of world-space shapes
+ * and an active camera transform.
+ *
+ * Layer order in the result follows first-appearance order; renderers iterate
+ * the array as-is (z-order is the caller's responsibility — typically scene
+ * layout uses the LayerId taxonomy to pre-sort).
+ */
+export declare function buildDrawCommands(shapes: Shape[], camera: CameraTransform): DrawCommandBatch[];