@bitmagic/world-forger 0.1.0

package/dist/artifact-types.d.ts

@@ -0,0 +1,295 @@
+/**
+ * The forged-artifact SCHEMA — the data shapes that cross from the private
+ * design/geometry half of the forger into the publishable half that drives the
+ * browser (archetype bakes, the level bake, instance placement and persist).
+ *
+ * These are declarations, not algorithms: a client that consumes a forge
+ * artifact at all has to know its shape, so the schema is public and the code
+ * that produces it is not. Each type is DEFINED here and re-exported from the
+ * module it used to live in (`forge-world.ts`, `derive-settings.ts`,
+ * `dungeon/dressing.ts`, `course.ts`, `dungeon/fixture-parts.ts`), so there is
+ * still exactly one definition of each and every historic import site keeps
+ * working.
+ *
+ * This file imports nothing.
+ */
+export interface WorldMarker {
+    name: string;
+    /** Position in GLB/spec space (origin at level center). */
+    glb: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Position in baked world space (world min corner is the origin). */
+    world: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+export interface ForgedPlacement {
+    archetype: string;
+    /** WORLD-space position (object origin / base on the ground). */
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationYDeg: number;
+    scale: number;
+    /** Per-axis scale (overrides uniform `scale` when present); city buildings. */
+    scaleXYZ?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    collision: boolean;
+    /** Loose prop: placed as an individual dynamic rigid body that settles under
+     *  gravity and sleeps until pushed (wrecks, barrels) — not a static batch. */
+    dynamic?: boolean;
+    /** Authored mass in kg for `dynamic` placements (omitted → engine estimate). */
+    mass?: number;
+}
+/** How an object's geometry collides in the bake. */
+export type ColliderKind = 'trimesh' | 'voxel' | 'none';
+/** One line of the forge's object report (the summary the caller reads). */
+export interface ForgedObjectSummary {
+    name: string;
+    kind: 'level' | 'asset';
+    triangles: number;
+    instances?: number;
+    smooth: boolean;
+    collider: ColliderKind;
+}
+/** A terrain LOD band the forger chose (node name -> lodOffset), for reporting. */
+export interface ForgedTerrainBand {
+    name: string;
+    lodOffset: number;
+}
+export interface CoursePoint {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface CourseCheckpoint extends CoursePoint {
+    /** Arc-length fraction along the course (0 = start, 1 = finish/lap). */
+    t: number;
+}
+/**
+ * A declared runtime behavior (ski lift, elevator, door) with its anchors
+ * resolved to world coordinates — the handoff the game's coding agent
+ * implements with engine systems. The level bakes geometry; features carry
+ * the intent the geometry alone cannot.
+ */
+export interface ResolvedFeature {
+    kind: string;
+    name: string;
+    description: string;
+    /** Single-point anchors: props, markers and structures — one entry each. */
+    anchors: Array<{
+        name: string;
+        x: number;
+        y: number;
+        z: number;
+    }>;
+    /**
+     * Instanced sets this feature is about — a scatter archetype ("CoconutPalms")
+     * or a city building type, where the intent is EVERY instance, not one of them.
+     *
+     * Per-instance positions are deliberately NOT inlined. A real level places up
+     * to ~640 instances of a single archetype, and these features are rendered
+     * verbatim into the coding agent's prompt AND persisted into world.json — so
+     * inlining would make both scale with instance count. The positions are already
+     * reachable: resolve `name` → `asset_id` through `library_assets`, then read
+     * world.json `environmentObjects`. This payload stays O(archetypes).
+     */
+    archetypeAnchors?: Array<{
+        name: string;
+        instances: number;
+        centroid: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    }>;
+    points: Array<{
+        x: number;
+        y: number;
+        z: number;
+    }>;
+    /** Open structured parameters carried verbatim to the game's coding agent (e.g. lock id,
+     *  timing, spawn-candidate metadata). `points` are world-resolved; `params` is opaque. */
+    params?: Record<string, unknown>;
+}
+/**
+ * Auto-emitted for every designed path: the level's intended flow as ordered
+ * world-space control points (dense through sharp turns, at most ~8 m apart
+ * on straights) with start/finish/checkpoints. The designed path is
+ * authoritative intent — game code should consume this rather than derive a
+ * line from the baked surface (which is lossy and closed-loop-only).
+ */
+export interface ResolvedPathFeature extends ResolvedFeature {
+    kind: 'path';
+    /** Ribbon width in meters (world space). */
+    widthM: number;
+    /** True for circuits: the last point connects back to the first. */
+    closed: boolean;
+    /** 3D arc length of the control polyline (m). */
+    lengthM: number;
+    /** First control point — the intended start of travel. */
+    start: CoursePoint;
+    /** Last control point (the lap point itself for closed circuits). */
+    finish: CoursePoint;
+    /** Evenly spaced by arc length, strictly between start and finish. */
+    checkpoints: CourseCheckpoint[];
+    /** Ribbon node name when its surface is queryable via the named-trimesh API. */
+    surfaceObjectName?: string;
+}
+/** Mirror of the engine handler's `options` payload. */
+export interface LevelVoxelizeOptions {
+    levelSizeX: number;
+    levelSizeZ: number;
+    /**
+     * NEVER set by the forger. A present `levelSizeY` switches the engine's
+     * `applyLevelSizeTransform` to a NON-uniform Y scale, while
+     * `marker-transform.ts` — the agent-side mirror every marker, door, key,
+     * spawn, water and nav Y is mapped through — assumes the uniform scale. The
+     * engine's `worldExtentY` already auto-sizes the level box from geometry,
+     * which is what a dungeon hanging under the terrain plate needs.
+     */
+    levelSizeY?: number;
+    chunkSize: number;
+    minVoxelSize: number;
+    maxVoxelSize: number;
+    fillInterior: boolean;
+    additionalLods?: Array<{
+        minVoxelSize: number;
+        maxVoxelSize: number;
+        distance?: number;
+    }>;
+    objectLodOffsets?: Record<string, number>;
+    objectLodPins?: Record<string, true>;
+    objectTrimeshColliders?: Record<string, true>;
+    objectNoColliders?: Record<string, true>;
+    objectCollisionOnlyNodes?: Record<string, true>;
+    objectDisplacementAxes?: Record<string, 'x' | 'y' | 'z'>;
+    /**
+     * Objects EXCLUDED from the level bake — they are library-asset instance
+     * groups (tagged in the GLB) placed as environment objects instead.
+     */
+    objectAssetInstances?: Record<string, true>;
+    /**
+     * Per-object GROUND TYPE names (see the engine's `vxlscene/GroundTypes.ts`
+     * registry, mirrored in `city/ground-style.ts`). The bake rasterizes the
+     * tagged nodes' triangles into the level's ground mask, which drives the
+     * runtime cobble domes and grass ground cover.
+     */
+    objectGroundTypes?: Record<string, string>;
+    /**
+     * Authored `#RRGGBB` → emissive strength (16..255). The bake matches these
+     * against the palette colors it actually produces and writes the matching
+     * cells into the level's emissive block, so glowing runes, lava seams and
+     * crystal veins light up at zero light-budget cost. Dungeon palettes are the
+     * only producer today.
+     */
+    emissiveByColor?: Record<string, number>;
+}
+export type DoorAnimation = 'hinge' | 'slide' | 'dissolve';
+export interface DungeonLightConfig {
+    color: string;
+    intensity: number;
+    distance: number;
+    flicker: boolean;
+    offset?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/**
+ * Spec-space mirrors of `DoorDefinition` / `KeyItemDefinition` in
+ * `game/src/types/game.ts`, minus the fields the PIPELINE owns: `levelId`
+ * (assigned at persist) and `assetId` (assigned once the archetype is baked).
+ * Mirrored rather than imported — the agent project does not compile the game
+ * project's sources — so any field added there must be added here too.
+ */
+export interface DungeonDoorDef {
+    id: string;
+    /** Closed-pose CENTRE of the leaf. */
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Yaw in RADIANS. Door-local X is the width, Z the thickness. */
+    rotationY: number;
+    width: number;
+    height: number;
+    thickness: number;
+    kind: 'plain' | 'locked';
+    keyId?: string;
+    animation: DoorAnimation;
+    /** Explicit for forged hinge doors; the engine retains 100° when omitted. */
+    maxOpenAngleDeg?: number;
+    /** Fallback box-leaf tint used until an asset is wired. */
+    color?: string;
+    autoOpenRadius?: number;
+}
+export interface DungeonKeyItemDef {
+    id: string;
+    keyId: string;
+    name: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    color?: string;
+}
+/**
+ * A NARROWED view of the designed scene spec (`scene-spec.ts`'s
+ * `WorldSceneSpec`, which stays private): exactly the fields the persist step
+ * reads, plus the identity it echoes back in the summary. The full validated
+ * spec is what actually travels — it is written verbatim onto the level asset
+ * record as `worldForgerSpec` — this type just declares the part any consumer
+ * of a forge artifact is entitled to depend on.
+ *
+ * Narrowing rather than restating is what keeps it honest: the private
+ * `WorldSceneSpec` is widened into this view in ONE place, so a field renamed
+ * or dropped over there fails to compile rather than drifting. That check only
+ * bites for the REQUIRED fields, though — `dungeon` and `city` are optional
+ * here, so renaming either away on the private side would still compile and
+ * would silently stop a dungeon getting its atmosphere. The producer therefore
+ * names both fields explicitly rather than relying on a bare assignment; see
+ * `toForgedSpecView` in the private half's `forge-and-upload-level.ts`.
+ */
+export interface ForgedSpecMaterialView {
+    name: string;
+    role: string;
+    color: string;
+    emissive?: {
+        strength: number;
+    };
+}
+/** The dungeon plan's palette — all the level atmosphere is derived from. */
+export interface ForgedDungeonView {
+    materials: ForgedSpecMaterialView[];
+}
+/** The city plan's zones — the persist step only asks whether any is water. */
+export interface ForgedCityView {
+    zones?: Array<{
+        kind: string;
+    }>;
+}
+export interface ForgedSpecView {
+    name: string;
+    size: {
+        x: number;
+        z: number;
+    };
+    /** Present iff the level is a dungeon (drives spawn clearance + atmosphere). */
+    dungeon?: ForgedDungeonView;
+    city?: ForgedCityView;
+}
+//# sourceMappingURL=artifact-types.d.ts.map

package/dist/artifact-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-types.d.ts","sourceRoot":"","sources":["../src/artifact-types.ts"],"names":[],"mappings":"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"}

package/dist/artifact-types.js

@@ -0,0 +1,17 @@
+/**
+ * The forged-artifact SCHEMA — the data shapes that cross from the private
+ * design/geometry half of the forger into the publishable half that drives the
+ * browser (archetype bakes, the level bake, instance placement and persist).
+ *
+ * These are declarations, not algorithms: a client that consumes a forge
+ * artifact at all has to know its shape, so the schema is public and the code
+ * that produces it is not. Each type is DEFINED here and re-exported from the
+ * module it used to live in (`forge-world.ts`, `derive-settings.ts`,
+ * `dungeon/dressing.ts`, `course.ts`, `dungeon/fixture-parts.ts`), so there is
+ * still exactly one definition of each and every historic import site keeps
+ * working.
+ *
+ * This file imports nothing.
+ */
+export {};
+//# sourceMappingURL=artifact-types.js.map

package/dist/artifact-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-types.js","sourceRoot":"","sources":["../src/artifact-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/forge-constants.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The dependency-free leaf: every constant and pure predicate that BOTH halves
+ * of the world forger need.
+ *
+ * The forger splits in two — the private design/geometry half (`forge-world.ts`,
+ * `scene-spec.ts`, the geometry tree, the designer and the director) and the
+ * publishable half that drives the browser steps (archetype bakes, the level
+ * bake, instance placement + persist). A handful of numbers and one predicate
+ * are genuinely shared. Left where they were, importing them would drag
+ * `forge-world.ts` (700+ lines, and through it `build-scene`, `glb-write`,
+ * `dungeon/nav-compile`, `marker-transform` and `heightfield`) or `city/zones.ts`
+ * (`geometry`, `street-graph`, `ground-style`) — and therefore three.js — into
+ * the publishable half for the sake of three numbers.
+ *
+ * So this file imports NOTHING, and every previous home re-exports from here so
+ * each symbol still has exactly one definition. Add to it only what both halves
+ * actually need; it is a boundary, not a junk drawer.
+ */
+/**
+ * Absolute LOD0 leaf ceiling for one archetype bake — the bake loop re-bakes at
+ * doubled voxel sizes until the count fits. Per-archetype TARGETS below are what
+ * actually size the bake; this is only the runaway backstop.
+ */
+export declare const ASSET_LOD0_VOXEL_BUDGET = 500000;
+/**
+ * The LOD0 leaf TARGET for an ordinary (non-landmark) archetype — what actually
+ * sizes a standard bake. Its landmark sibling stays in derive-settings.ts, which
+ * is the only thing that reads it; this one crosses because the pipeline's own
+ * bake-loop tests assert against it.
+ */
+export declare const ASSET_STANDARD_LOD0_TARGET = 50000;
+/**
+ * Spawn this far above the marker so the player drops onto the surface —
+ * outdoors only. A dungeon spawn instead is authored with clearance 0: the
+ * entrance cell's Y (see `dressing.ts` — "FLOOR TRUTH", taken from the floor
+ * grid, never from `room.floorY`) already IS the true floor, so `player_0` is
+ * written exactly there. The engine (`game/src/engine/loaders/PlayerLoader.ts`)
+ * seats the capsule on the floor beneath a configured interior spawn itself (a
+ * bounded downward search) rather than lifting an authored point, so the
+ * forger no longer needs to predict engine lift constants or bake-regime floor
+ * heights. See the `clearanceM` choice in `place-and-persist-level.ts`.
+ */
+export declare const SPAWN_CLEARANCE_M = 1.5;
+/** Sea level (world Y) the engine renders the water surface at — just below the land base so the
+ *  land occludes the plane and only the dug basins (floor at -WATER_DEPTH) reveal the see-through sea. */
+export declare const WATER_SURFACE_Y = -2;
+/** Bake pitch of a wall module. Every relief feature is a whole multiple of it. */
+export declare const VOXEL_M = 0.0625;
+/** Modules bake at this pitch, pinned rather than left to the archetype
+ *  budget's clamp — a coarser bake silently deletes ALL relief. */
+export declare const MODULE_MIN_VOXEL_M = 0.0625;
+/** Top-level GLB node-name prefix. The bake and structural fail-fast path both
+ *  branch on it; used modules are never dropped or degraded to shell. */
+export declare const MODULE_NAME_PREFIX = "Mod_";
+/**
+ * Question: MIGHT this archetype's instance group be a module kit's, and so
+ * bloat the world GLB the way the kit's groups do? Deliberately loose — the
+ * reserved `Mod_` name prefix (module-kit.ts) and nothing else.
+ *
+ * Fails safe by OVER-matching. A false positive drops one redundant
+ * self-description copy of an object from a file only a manual GLB viewer and
+ * the Assets-tab bake fallback ever read; the archetype's own asset and every
+ * placement are written elsewhere and are untouched. A false negative puts a
+ * several-hundred-instance group back into the world GLB — the measured case
+ * was 567 module placements replaying a shared mesh for 23.7M effective
+ * triangles, which burned the full 20-minute bake timeout on a level that
+ * forged in 95 s without them. Over-matching costs a viewer copy;
+ * under-matching costs the run.
+ */
+export declare function isModuleNamedArchetype(name: string): boolean;
+/**
+ * Question: IS this archetype really one of the kit's own pieces, so its bake
+ * may be PINNED to the kit's voxel size and its interior left unfilled? The
+ * reserved prefix AND the non-colliding decorative flag `dungeon-expand.ts`'s
+ * `moduleArchetype` sets on every piece — the same pair `archetype-skips.ts`'s
+ * `isCladdingModule` requires.
+ *
+ * Fails safe by UNDER-matching, the opposite direction from the predicate
+ * above, which is why the two must stay separate rather than share one test. A
+ * false negative costs nothing today: every real kit piece is small enough that
+ * `deriveArchetypeVoxelBake` floor-clamps to this same value anyway, so the pin
+ * is a guarantee against future kit or budget changes, not a live behaviour
+ * change. A false positive is the expensive direction, and the pin is the only
+ * branch here with a live effect at all: `bake.minVoxelSize` is already floored
+ * at ASSET_MIN_VOXEL_SIZE, which IS MODULE_MIN_VOXEL_M, so pinning can only
+ * make a bake FINER, never coarser. `scene-spec.ts`'s `nodeName` lets an LLM
+ * legally name any object `Mod_*` in any genre and nothing in the repo reserves
+ * the prefix, so a prefix-only pin would bake, say, a `Mod_Tower` in a city
+ * forge at roughly 13x the surface cells — and that timeout is FATAL, because
+ * `archetype-skips.ts`'s `isCladdingModule` would (correctly) refuse to class a
+ * colliding object as droppable. Nothing downstream rescues it either: the
+ * pipeline's coarsen-rebake loop, which used to double a misfired pin back out
+ * of trouble, now leaves modules at their pinned size precisely so a REAL
+ * module's relief survives. Same mechanism, opposite roles — with that net
+ * gone, this narrowing is the guard.
+ *
+ * This lives in the leaf rather than in `forge-world.ts` because BOTH halves
+ * decide with it: the forger pins the bake resolution here, and the pipeline's
+ * `isCladdingModule` classifies the same archetype the same way. Restating it
+ * on one side would silently mis-resolve bakes with every test still green.
+ */
+export declare function isKitModuleArchetype(archetype: {
+    name: string;
+    collision: boolean;
+}): boolean;
+//# sourceMappingURL=forge-constants.d.ts.map

package/dist/forge-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forge-constants.d.ts","sourceRoot":"","sources":["../src/forge-constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,SAAU,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAIjD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAIrC;0GAC0G;AAC1G,eAAO,MAAM,eAAe,KAAK,CAAC;AAIlC,mFAAmF;AACnF,eAAO,MAAM,OAAO,SAAS,CAAC;AAE9B;mEACmE;AACnE,eAAO,MAAM,kBAAkB,SAAU,CAAC;AAE1C;yEACyE;AACzE,eAAO,MAAM,kBAAkB,SAAS,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAE7F"}

package/dist/forge-constants.js

@@ -0,0 +1,111 @@
+/**
+ * The dependency-free leaf: every constant and pure predicate that BOTH halves
+ * of the world forger need.
+ *
+ * The forger splits in two — the private design/geometry half (`forge-world.ts`,
+ * `scene-spec.ts`, the geometry tree, the designer and the director) and the
+ * publishable half that drives the browser steps (archetype bakes, the level
+ * bake, instance placement + persist). A handful of numbers and one predicate
+ * are genuinely shared. Left where they were, importing them would drag
+ * `forge-world.ts` (700+ lines, and through it `build-scene`, `glb-write`,
+ * `dungeon/nav-compile`, `marker-transform` and `heightfield`) or `city/zones.ts`
+ * (`geometry`, `street-graph`, `ground-style`) — and therefore three.js — into
+ * the publishable half for the sake of three numbers.
+ *
+ * So this file imports NOTHING, and every previous home re-exports from here so
+ * each symbol still has exactly one definition. Add to it only what both halves
+ * actually need; it is a boundary, not a junk drawer.
+ */
+// ── Archetype bake budgets (derive-settings.ts) ──────────────────────────────
+/**
+ * Absolute LOD0 leaf ceiling for one archetype bake — the bake loop re-bakes at
+ * doubled voxel sizes until the count fits. Per-archetype TARGETS below are what
+ * actually size the bake; this is only the runaway backstop.
+ */
+export const ASSET_LOD0_VOXEL_BUDGET = 500000;
+/**
+ * The LOD0 leaf TARGET for an ordinary (non-landmark) archetype — what actually
+ * sizes a standard bake. Its landmark sibling stays in derive-settings.ts, which
+ * is the only thing that reads it; this one crosses because the pipeline's own
+ * bake-loop tests assert against it.
+ */
+export const ASSET_STANDARD_LOD0_TARGET = 50000;
+// ── Spawn (forge-world.ts) ───────────────────────────────────────────────────
+/**
+ * Spawn this far above the marker so the player drops onto the surface —
+ * outdoors only. A dungeon spawn instead is authored with clearance 0: the
+ * entrance cell's Y (see `dressing.ts` — "FLOOR TRUTH", taken from the floor
+ * grid, never from `room.floorY`) already IS the true floor, so `player_0` is
+ * written exactly there. The engine (`game/src/engine/loaders/PlayerLoader.ts`)
+ * seats the capsule on the floor beneath a configured interior spawn itself (a
+ * bounded downward search) rather than lifting an authored point, so the
+ * forger no longer needs to predict engine lift constants or bake-regime floor
+ * heights. See the `clearanceM` choice in `place-and-persist-level.ts`.
+ */
+export const SPAWN_CLEARANCE_M = 1.5;
+// ── Water (city/zones.ts) ────────────────────────────────────────────────────
+/** Sea level (world Y) the engine renders the water surface at — just below the land base so the
+ *  land occludes the plane and only the dug basins (floor at -WATER_DEPTH) reveal the see-through sea. */
+export const WATER_SURFACE_Y = -2;
+// ── Dungeon module kit (dungeon/module-stone.ts, dungeon/module-kit.ts) ──────
+/** Bake pitch of a wall module. Every relief feature is a whole multiple of it. */
+export const VOXEL_M = 0.0625;
+/** Modules bake at this pitch, pinned rather than left to the archetype
+ *  budget's clamp — a coarser bake silently deletes ALL relief. */
+export const MODULE_MIN_VOXEL_M = VOXEL_M;
+/** Top-level GLB node-name prefix. The bake and structural fail-fast path both
+ *  branch on it; used modules are never dropped or degraded to shell. */
+export const MODULE_NAME_PREFIX = 'Mod_';
+/**
+ * Question: MIGHT this archetype's instance group be a module kit's, and so
+ * bloat the world GLB the way the kit's groups do? Deliberately loose — the
+ * reserved `Mod_` name prefix (module-kit.ts) and nothing else.
+ *
+ * Fails safe by OVER-matching. A false positive drops one redundant
+ * self-description copy of an object from a file only a manual GLB viewer and
+ * the Assets-tab bake fallback ever read; the archetype's own asset and every
+ * placement are written elsewhere and are untouched. A false negative puts a
+ * several-hundred-instance group back into the world GLB — the measured case
+ * was 567 module placements replaying a shared mesh for 23.7M effective
+ * triangles, which burned the full 20-minute bake timeout on a level that
+ * forged in 95 s without them. Over-matching costs a viewer copy;
+ * under-matching costs the run.
+ */
+export function isModuleNamedArchetype(name) {
+    return name.startsWith(MODULE_NAME_PREFIX);
+}
+/**
+ * Question: IS this archetype really one of the kit's own pieces, so its bake
+ * may be PINNED to the kit's voxel size and its interior left unfilled? The
+ * reserved prefix AND the non-colliding decorative flag `dungeon-expand.ts`'s
+ * `moduleArchetype` sets on every piece — the same pair `archetype-skips.ts`'s
+ * `isCladdingModule` requires.
+ *
+ * Fails safe by UNDER-matching, the opposite direction from the predicate
+ * above, which is why the two must stay separate rather than share one test. A
+ * false negative costs nothing today: every real kit piece is small enough that
+ * `deriveArchetypeVoxelBake` floor-clamps to this same value anyway, so the pin
+ * is a guarantee against future kit or budget changes, not a live behaviour
+ * change. A false positive is the expensive direction, and the pin is the only
+ * branch here with a live effect at all: `bake.minVoxelSize` is already floored
+ * at ASSET_MIN_VOXEL_SIZE, which IS MODULE_MIN_VOXEL_M, so pinning can only
+ * make a bake FINER, never coarser. `scene-spec.ts`'s `nodeName` lets an LLM
+ * legally name any object `Mod_*` in any genre and nothing in the repo reserves
+ * the prefix, so a prefix-only pin would bake, say, a `Mod_Tower` in a city
+ * forge at roughly 13x the surface cells — and that timeout is FATAL, because
+ * `archetype-skips.ts`'s `isCladdingModule` would (correctly) refuse to class a
+ * colliding object as droppable. Nothing downstream rescues it either: the
+ * pipeline's coarsen-rebake loop, which used to double a misfired pin back out
+ * of trouble, now leaves modules at their pinned size precisely so a REAL
+ * module's relief survives. Same mechanism, opposite roles — with that net
+ * gone, this narrowing is the guard.
+ *
+ * This lives in the leaf rather than in `forge-world.ts` because BOTH halves
+ * decide with it: the forger pins the bake resolution here, and the pipeline's
+ * `isCladdingModule` classifies the same archetype the same way. Restating it
+ * on one side would silently mis-resolve bakes with every test still green.
+ */
+export function isKitModuleArchetype(archetype) {
+    return isModuleNamedArchetype(archetype.name) && archetype.collision === false;
+}
+//# sourceMappingURL=forge-constants.js.map

package/dist/forge-constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forge-constants.js","sourceRoot":"","sources":["../src/forge-constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,gFAAgF;AAEhF;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAO,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAM,CAAC;AAEjD,gFAAgF;AAEhF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC,gFAAgF;AAEhF;0GAC0G;AAC1G,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,CAAC;AAElC,gFAAgF;AAEhF,mFAAmF;AACnF,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC;AAE9B;mEACmE;AACnE,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAE1C;yEACyE;AACzE,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAA+C;IAClF,OAAO,sBAAsB,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,SAAS,KAAK,KAAK,CAAC;AACjF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@bitmagic/world-forger` — the CLIENT half of the world forger.
+ *
+ * The forger runs in two halves. The DESIGN and GEOMETRY half (an LLM designs a
+ * level, deterministic code builds its meshes) is private, is not published, and
+ * stays server-side. This package is everything a host needs to consume what
+ * that half produces:
+ *
+ *  - the forged-level ARTIFACT SCHEMA (artifact-types.ts, pipeline/job-types.ts)
+ *    — placements, markers, resolved gameplay features, dungeon doors/keys/
+ *    lights, the terrain height grid and the level bake options,
+ *  - the HOST SEAMS the pipeline runs behind (storage, model, transport,
+ *    world.json, logger — see pipeline/deps.ts),
+ *  - the three BROWSER STEPS themselves: create the archetype library assets,
+ *    bake the level, place the instances and plan the world.json write.
+ *
+ * Nothing here touches geometry, and it deliberately has no three.js — the steps
+ * orchestrate a browser that does the heavy work, and the artifact that reaches
+ * them is already plain JSON.
+ *
+ * The pipeline is reachable as `@bitmagic/world-forger/pipeline/index.js`;
+ * every module is reachable by its own subpath (e.g.
+ * `@bitmagic/world-forger/pipeline/transport-types.js`).
+ */
+export * from './artifact-types.js';
+export * from './forge-constants.js';
+export * from './terrain-height-grid.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * `@bitmagic/world-forger` — the CLIENT half of the world forger.
+ *
+ * The forger runs in two halves. The DESIGN and GEOMETRY half (an LLM designs a
+ * level, deterministic code builds its meshes) is private, is not published, and
+ * stays server-side. This package is everything a host needs to consume what
+ * that half produces:
+ *
+ *  - the forged-level ARTIFACT SCHEMA (artifact-types.ts, pipeline/job-types.ts)
+ *    — placements, markers, resolved gameplay features, dungeon doors/keys/
+ *    lights, the terrain height grid and the level bake options,
+ *  - the HOST SEAMS the pipeline runs behind (storage, model, transport,
+ *    world.json, logger — see pipeline/deps.ts),
+ *  - the three BROWSER STEPS themselves: create the archetype library assets,
+ *    bake the level, place the instances and plan the world.json write.
+ *
+ * Nothing here touches geometry, and it deliberately has no three.js — the steps
+ * orchestrate a browser that does the heavy work, and the artifact that reaches
+ * them is already plain JSON.
+ *
+ * The pipeline is reachable as `@bitmagic/world-forger/pipeline/index.js`;
+ * every module is reachable by its own subpath (e.g.
+ * `@bitmagic/world-forger/pipeline/transport-types.js`).
+ */
+export * from './artifact-types.js';
+export * from './forge-constants.js';
+export * from './terrain-height-grid.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC"}

package/dist/log.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Minimal dependency-free logger for this package. `shared/world-forger` must
+ * stay free of game-play-agent's pino/fs-backed logger (`src/utils/logger.ts`)
+ * — see the package README-equivalent purity rule in the extraction task —
+ * so this mirrors just the pino call shape `city-expand.ts` uses
+ * (`log.warn(context, message)` / `log.info(context, message)`) over plain
+ * console output.
+ *
+ * This is NOT a general injectable-logger seam, and deliberately stays that
+ * way. Two modules use it — `pipeline/asset-catalog.ts` and
+ * `pipeline/forged-work-store.ts` — and both log housekeeping detail (a
+ * skipped catalog entry, a store read) that no host has ever needed to route
+ * anywhere. Everything a host DOES care about already goes through the real
+ * seam: `ForgeDeps.logger` (see pipeline/deps.ts), which every pipeline step
+ * logs through and which the web lane points at pino and the CLI lane at the
+ * creator's terminal. Adding a second injectable logger for these two call
+ * sites would duplicate that seam rather than complete it.
+ */
+export interface Logger {
+    info(context: Record<string, unknown>, message: string): void;
+    warn(context: Record<string, unknown>, message: string): void;
+    error(context: Record<string, unknown>, message: string): void;
+    debug(context: Record<string, unknown>, message: string): void;
+}
+export declare function createLogger(name: string): Logger;
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9D,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/D,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAChE;AAQD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOjD"}