@rpgm-tools/neo-angband-core 0.10.0

package/dist/index.js

@@ -0,0 +1,222 @@
+/**
+ * @rpgm-tools/neo-angband-core - the headless game engine.
+ *
+ * Phase 0 scaffold. The engine grows here by dependency order:
+ * rng -> dice/expressions -> flags -> world kernel -> entities ->
+ * effects -> game loop. See docs/PORT_PLAN.md at the repository root.
+ *
+ * Parity baseline: Angband 4.2.6 (see reference/ and parity/).
+ */
+export * from "./rng.js";
+export * from "./loc.js";
+export * from "./events.js";
+export * from "./cmd.js";
+export * from "./msg.js";
+export * from "./color.js";
+export * from "./bitflag.js";
+export * from "./guard.js";
+export * from "./expression.js";
+export * from "./dice.js";
+export * from "./generated/index.js";
+export * from "./constants.js";
+export * from "./version.js";
+export * from "./world/feature.js";
+export * from "./world/chunk.js";
+export * from "./world/view.js";
+export * from "./world/scatter.js";
+export * from "./world/flow.js";
+export * from "./world/project.js";
+export * from "./world/projection.js";
+export * from "./world/trap.js";
+export * from "./effects/effect.js";
+export * from "./effects/effect-info.js";
+export * from "./effects/effect-choice.js";
+export * from "./effects/interpreter.js";
+export * from "./effects/handlers.js";
+export * from "./mon/types.js";
+export * from "./mon/bind.js";
+export * from "./mon/monster.js";
+export * from "./mon/make.js";
+export * from "./mon/summon.js";
+export * from "./mon/predicate.js";
+export * from "./mon/timed.js";
+export * from "./mon/take-hit.js";
+export * from "./mon/spell.js";
+export * from "./mon/desc.js";
+export * from "./mon/knowledge-groups.js";
+export * from "./mon/project-mon.js";
+export * from "./obj/types.js";
+export * from "./obj/bind.js";
+export * from "./obj/object.js";
+export * from "./obj/chest.js";
+export * from "./obj/make.js";
+export * from "./obj/power.js";
+export * from "./obj/value.js";
+export * from "./obj/knowledge.js";
+export * from "./obj/ignore.js";
+export * from "./obj/known-object.js";
+export * from "./obj/artifact-known.js";
+export * from "./obj/artifact-fake.js";
+export * from "./obj/desc.js";
+export * from "./obj/object-info.js";
+export * from "./obj/randname.js";
+export * from "./obj/flavor.js";
+export * from "./obj/randart.js";
+export * from "./player/types.js";
+export * from "./player/options.js";
+export * from "./player/bind.js";
+export * from "./player/player.js";
+export * from "./player/calcs.js";
+export * from "./player/timed.js";
+export * from "./player/take-hit.js";
+export * from "./player/spell.js";
+export * from "./player/birth.js";
+export * from "./player/history.js";
+export * from "./player/abilities.js";
+export * from "./player/shape-lore.js";
+export * from "./save/buffer.js";
+export * from "./save/compress.js";
+export * from "./save/description.js";
+export * from "./save/integrity.js";
+export * from "./gen/util.js";
+export * from "./gen/room.js";
+export * from "./gen/cave.js";
+export * from "./gen/generate.js";
+/* gen-monster's pit machinery: resolvePits is the last piece of a GenDeps a
+ * caller outside core cannot otherwise build, so a mod that wants to run
+ * generateLevel itself (or test a levelGenerated hook against real levels) needs
+ * it. Everything else here is the same generation vocabulary gen/util already
+ * publishes. */
+export * from "./gen/gen-monster.js";
+export * from "./combat/index.js";
+export * from "./store/types.js";
+export * from "./store/bind.js";
+export * from "./store/price.js";
+export * from "./store/store.js";
+export * from "./store/transact.js";
+export * from "./store/store-cmd.js";
+export * from "./session/boot.js";
+export * from "./session/game.js";
+export * from "./session/save.js";
+/* The behaviour seam itself: ModHooks (the closed set of extension points) and
+ * composeModHooks (the host's fold over several mods' contributions). A mod
+ * cannot write a hook without the type, and a host cannot install one without
+ * the fold, so both are part of the published API - see mod/hooks.ts. */
+export * from "./mod/hooks.js";
+export * from "./mod/save-blocks.js";
+export * from "./mod/ids.js";
+export * from "./mod/registry-host.js";
+export * from "./mod/vocabulary.js";
+export * from "./agent/index.js";
+export * from "./game/energy.js";
+export * from "./game/context.js";
+export * from "./game/monster-turn.js";
+export * from "./game/scheduler.js";
+export * from "./game/player-turn.js";
+export * from "./game/project-monster.js";
+export * from "./game/project-player.js";
+export * from "./game/project-cast.js";
+export * from "./game/effect-env.js";
+export * from "./game/effect-game-env.js";
+export * from "./game/effect-attack.js";
+export * from "./game/effect-general.js";
+export * from "./game/effect-monster.js";
+export * from "./game/effect-teleport.js";
+export * from "./game/effect-terrain.js";
+export * from "./game/effect-item.js";
+export * from "./game/effect-melee.js";
+export * from "./game/effect-summon.js";
+export * from "./game/effect-detect.js";
+export * from "./game/known.js";
+export * from "./game/inscription-confirm.js";
+export * from "./game/target.js";
+export * from "./game/target-loop.js";
+export * from "./game/mon-cmd.js";
+export * from "./game/describe.js";
+export * from "./game/history.js";
+export * from "./game/object-inspect.js";
+export * from "./game/mon-message.js";
+export * from "./game/mon-list.js";
+export * from "./game/obj-list.js";
+export * from "./game/display.js";
+export * from "./game/char-sheet.js";
+export * from "./game/lore-color.js";
+export * from "./game/ui-entry.js";
+export * from "./game/equip-cmp.js";
+export * from "./game/mon-shape.js";
+export * from "./mon/lore.js";
+export * from "./mon/lore-describe.js";
+/* The live-cave placement family shares upstream names with its
+ * generation-time twin in gen/util; the live variants export Live-suffixed. */
+export { squareIsOpenLive, squareIsEmptyLive, squareAllowsSummon, placeNewMonsterOne, placeNewMonster as placeNewMonsterLive, pickAndPlaceMonster as pickAndPlaceMonsterLive, summonSpecific, selectShape, wipeMonsterCounts, countMonsterRaces, } from "./game/mon-place.js";
+export * from "./game/thrust.js";
+export * from "./game/mon-cast.js";
+export * from "./game/mon-ranged.js";
+export * from "./game/mon-group.js";
+export * from "./game/floor.js";
+export * from "./game/dump-level.js";
+export * from "./game/spoil.js";
+export * from "./game/pickup.js";
+export * from "./game/obj-cmd.js";
+export * from "./game/cave-cmd.js";
+export * from "./game/chest.js";
+export * from "./game/trap.js";
+export * from "./game/spell-cmd.js";
+export * from "./game/ranged-cmd.js";
+export * from "./game/loop.js";
+export * from "./game/ignore-cmd.js";
+/* --- Wizard / debug commands (task #29: cmd-wizard.c / wiz-debug.c) ---
+ * The debug/cheat command surface, gated behind the WizardDeps.wizard flag
+ * (upstream ALLOW_DEBUG + NOSCORE_WIZARD); unreachable in faithful play. */
+export * from "./game/wizard.js";
+export * from "./sound/index.js";
+/* --- High scores (task #28: score.c / score-util.c / ui-score.c) --- */
+export * from "./score/types.js";
+export * from "./score/score.js";
+export * from "./score/display.js";
+/* --- Graphics/tiles + visuals (task #27: grafmode.c / ui-visuals.c) --- */
+export * from "./visuals/index.js";
+/* --- The host layer (z-file.c + init.c's ANGBAND_DIR_*) ---
+ * The injectable seam that lets a front end declare what its platform can do
+ * instead of letting the platform's limits quietly redefine the game. Adapters
+ * live with their front ends (web, cli, desktop); MemoryHost is the reference
+ * implementation and what the tests drive. */
+export * from "./host/io.js";
+export * from "./host/memory.js";
+export * from "./host/raw.js";
+export * from "./host/bridge.js";
+export * from "./host/args.js";
+// Some small derived constants and geometry helpers are defined
+// independently by more than one domain (identical values/behavior).
+// Re-export a single canonical copy so the barrel is unambiguous rather
+// than dropping the name from two colliding `export *`s.
+// - OF_SIZE/ELEM_MAX: flag-array sizes derived from the generated lists,
+//   defined by both obj/types and player/types.
+// - nextGrid: next_grid(grid, dir), defined by both world/view and
+//   gen/util as grid + DDGRID[dir].
+export { OF_SIZE, ELEM_MAX } from "./obj/types.js";
+export { nextGrid } from "./world/view.js";
+// objDescNameFormat: obj/bind has a reduced &-stripping helper (sval name
+// matching); obj/desc has the full obj_desc_name_format (modstr + pluralise).
+// Expose the full port as canonical; bind's stays internal to its module.
+export { objDescNameFormat } from "./obj/desc.js";
+// - EXTRACT_ENERGY/turnEnergy: the extract_energy[] table and turn_energy()
+//   live in mon/monster; game/energy re-exports them for convenience, so
+//   pin mon/monster as the single canonical source.
+// - squareIsEmpty: two genuinely different predicates share the name -
+//   gen/util's is a generation-time check (takes a Gen), game/context's is
+//   a live occupancy check (takes a GameState). Keep gen/util's as the
+//   barrel-canonical (it predates game/); game/context's is reached via its
+//   module and will get an aliased export if the game API needs it publicly.
+export { EXTRACT_ENERGY, turnEnergy } from "./mon/monster.js";
+export { squareIsEmpty } from "./gen/util.js";
+// - squareCanPutItem: like squareIsEmpty, a generation-time predicate
+//   (gen/util, takes a Gen) and a live-cave one (game/floor, takes a
+//   GameState) share the name; gen/util's stays barrel-canonical and the
+//   live one is reached via its module.
+export { squareCanPutItem } from "./gen/util.js";
+// - placeTrap: gen/util's generation-time marker vs game/trap's live
+//   place_trap; same convention, gen/util's stays barrel-canonical.
+export { placeTrap } from "./gen/util.js";
+export * from "./game/gear.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":"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"}

package/dist/loc.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Grid locations and keypad-direction tables, ported from
+ * reference/src/z-type.h, z-type.c, and the direction tables plus
+ * distance() from reference/src/cave.c and cave-view.c (Angband 4.2.6).
+ *
+ * Locations are plain immutable value objects; y grows downward (screen
+ * order) exactly as upstream. Directions use keypad numbering: 5 is
+ * "no direction", 2/4/6/8 orthogonal, 1/3/7/9 diagonal.
+ */
+import type { Rng } from "./rng.js";
+export interface Loc {
+    readonly x: number;
+    readonly y: number;
+}
+/** Construct a location. */
+export declare function loc(x: number, y: number): Loc;
+/** loc_eq: value equality. */
+export declare function locEq(a: Loc, b: Loc): boolean;
+/** loc_is_zero. */
+export declare function locIsZero(a: Loc): boolean;
+/** loc_sum. */
+export declare function locSum(a: Loc, b: Loc): Loc;
+/** loc_diff: a - b. */
+export declare function locDiff(a: Loc, b: Loc): Loc;
+/** loc_offset. */
+export declare function locOffset(a: Loc, dx: number, dy: number): Loc;
+/** rand_loc: a location spread uniformly around `grid`. */
+export declare function randLoc(rng: Rng, grid: Loc, xSpread: number, ySpread: number): Loc;
+/**
+ * distance: the upstream integer approximation
+ * (longer axis + half the shorter axis).
+ */
+export declare function distance(a: Loc, b: Loc): number;
+/**
+ * ddd: the cycle of directions, southward then clockwise, ending with 5.
+ */
+export declare const DDD: readonly number[];
+/** ddx: keypad direction -> x offset (index 0 unused). */
+export declare const DDX: readonly number[];
+/** ddy: keypad direction -> y offset (index 0 unused). */
+export declare const DDY: readonly number[];
+/** ddgrid: keypad direction -> Loc offset (index 0 unused). */
+export declare const DDGRID: readonly Loc[];
+/** ddx_ddd: x offsets in ddd order. */
+export declare const DDX_DDD: readonly number[];
+/** ddy_ddd: y offsets in ddd order. */
+export declare const DDY_DDD: readonly number[];
+/** ddgrid_ddd: Loc offsets in ddd order. */
+export declare const DDGRID_DDD: readonly Loc[];
+/**
+ * clockwise_ddd: can multiply the index by 45 degrees, e.g. index 6 is
+ * 270 degrees (9 o'clock).
+ */
+export declare const CLOCKWISE_DDD: readonly number[];
+/** clockwise_grid: Loc offsets in clockwise order starting north. */
+export declare const CLOCKWISE_GRID: readonly Loc[];
+/**
+ * side_dirs: alternative sideways/backup directions for each keypad
+ * direction, in order of decreasing desirability. Rows 0-9 bias right,
+ * rows 10-19 bias left.
+ */
+export declare const SIDE_DIRS: readonly (readonly number[])[];
+//# sourceMappingURL=loc.d.ts.map

package/dist/loc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loc.d.ts","sourceRoot":"","sources":["../src/loc.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEpC,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,4BAA4B;AAC5B,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,GAAG,CAE7C;AAED,8BAA8B;AAC9B,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,OAAO,CAE7C;AAED,mBAAmB;AACnB,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,GAAG,OAAO,CAEzC;AAED,eAAe;AACf,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,GAAG,CAE1C;AAED,uBAAuB;AACvB,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,GAAG,CAE3C;AAED,kBAAkB;AAClB,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,GAAG,CAE7D;AAED,2DAA2D;AAC3D,wBAAgB,OAAO,CACrB,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,GAAG,EACT,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,GAAG,CAEL;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAI/C;AAED;;GAEG;AACH,eAAO,MAAM,GAAG,EAAE,SAAS,MAAM,EAAgC,CAAC;AAElE,0DAA0D;AAC1D,eAAO,MAAM,GAAG,EAAE,SAAS,MAAM,EAAsC,CAAC;AAExE,0DAA0D;AAC1D,eAAO,MAAM,GAAG,EAAE,SAAS,MAAM,EAAsC,CAAC;AAExE,+DAA+D;AAC/D,eAAO,MAAM,MAAM,EAAE,SAAS,GAAG,EAWhC,CAAC;AAEF,uCAAuC;AACvC,eAAO,MAAM,OAAO,EAAE,SAAS,MAAM,EAAmC,CAAC;AAEzE,uCAAuC;AACvC,eAAO,MAAM,OAAO,EAAE,SAAS,MAAM,EAAmC,CAAC;AAEzE,4CAA4C;AAC5C,eAAO,MAAM,UAAU,EAAE,SAAS,GAAG,EAUpC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAAgC,CAAC;AAE5E,qEAAqE;AACrE,eAAO,MAAM,cAAc,EAAE,SAAS,GAAG,EAUxC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAqBnD,CAAC"}

package/dist/loc.js

@@ -0,0 +1,128 @@
+/**
+ * Grid locations and keypad-direction tables, ported from
+ * reference/src/z-type.h, z-type.c, and the direction tables plus
+ * distance() from reference/src/cave.c and cave-view.c (Angband 4.2.6).
+ *
+ * Locations are plain immutable value objects; y grows downward (screen
+ * order) exactly as upstream. Directions use keypad numbering: 5 is
+ * "no direction", 2/4/6/8 orthogonal, 1/3/7/9 diagonal.
+ */
+/** Construct a location. */
+export function loc(x, y) {
+    return { x, y };
+}
+/** loc_eq: value equality. */
+export function locEq(a, b) {
+    return a.x === b.x && a.y === b.y;
+}
+/** loc_is_zero. */
+export function locIsZero(a) {
+    return a.x === 0 && a.y === 0;
+}
+/** loc_sum. */
+export function locSum(a, b) {
+    return loc(a.x + b.x, a.y + b.y);
+}
+/** loc_diff: a - b. */
+export function locDiff(a, b) {
+    return loc(a.x - b.x, a.y - b.y);
+}
+/** loc_offset. */
+export function locOffset(a, dx, dy) {
+    return loc(a.x + dx, a.y + dy);
+}
+/** rand_loc: a location spread uniformly around `grid`. */
+export function randLoc(rng, grid, xSpread, ySpread) {
+    return loc(rng.randSpread(grid.x, xSpread), rng.randSpread(grid.y, ySpread));
+}
+/**
+ * distance: the upstream integer approximation
+ * (longer axis + half the shorter axis).
+ */
+export function distance(a, b) {
+    const ay = Math.abs(b.y - a.y);
+    const ax = Math.abs(b.x - a.x);
+    return ay > ax ? ay + (ax >> 1) : ax + (ay >> 1);
+}
+/**
+ * ddd: the cycle of directions, southward then clockwise, ending with 5.
+ */
+export const DDD = [2, 8, 6, 4, 3, 1, 9, 7, 5];
+/** ddx: keypad direction -> x offset (index 0 unused). */
+export const DDX = [0, -1, 0, 1, -1, 0, 1, -1, 0, 1];
+/** ddy: keypad direction -> y offset (index 0 unused). */
+export const DDY = [0, 1, 1, 1, 0, 0, 0, -1, -1, -1];
+/** ddgrid: keypad direction -> Loc offset (index 0 unused). */
+export const DDGRID = [
+    { x: 0, y: 0 },
+    { x: -1, y: 1 },
+    { x: 0, y: 1 },
+    { x: 1, y: 1 },
+    { x: -1, y: 0 },
+    { x: 0, y: 0 },
+    { x: 1, y: 0 },
+    { x: -1, y: -1 },
+    { x: 0, y: -1 },
+    { x: 1, y: -1 },
+];
+/** ddx_ddd: x offsets in ddd order. */
+export const DDX_DDD = [0, 0, 1, -1, 1, -1, 1, -1, 0];
+/** ddy_ddd: y offsets in ddd order. */
+export const DDY_DDD = [1, -1, 0, 0, 1, 1, -1, -1, 0];
+/** ddgrid_ddd: Loc offsets in ddd order. */
+export const DDGRID_DDD = [
+    { x: 0, y: 1 },
+    { x: 0, y: -1 },
+    { x: 1, y: 0 },
+    { x: -1, y: 0 },
+    { x: 1, y: 1 },
+    { x: -1, y: 1 },
+    { x: 1, y: -1 },
+    { x: -1, y: -1 },
+    { x: 0, y: 0 },
+];
+/**
+ * clockwise_ddd: can multiply the index by 45 degrees, e.g. index 6 is
+ * 270 degrees (9 o'clock).
+ */
+export const CLOCKWISE_DDD = [8, 9, 6, 3, 2, 1, 4, 7, 5];
+/** clockwise_grid: Loc offsets in clockwise order starting north. */
+export const CLOCKWISE_GRID = [
+    { x: 0, y: -1 },
+    { x: 1, y: -1 },
+    { x: 1, y: 0 },
+    { x: 1, y: 1 },
+    { x: 0, y: 1 },
+    { x: -1, y: 1 },
+    { x: -1, y: 0 },
+    { x: -1, y: -1 },
+    { x: 0, y: 0 },
+];
+/**
+ * side_dirs: alternative sideways/backup directions for each keypad
+ * direction, in order of decreasing desirability. Rows 0-9 bias right,
+ * rows 10-19 bias left.
+ */
+export const SIDE_DIRS = [
+    [0, 0, 0, 0, 0, 0, 0, 0],
+    [1, 4, 2, 7, 3, 8, 6, 9],
+    [2, 1, 3, 4, 6, 7, 9, 8],
+    [3, 2, 6, 1, 9, 4, 8, 7],
+    [4, 7, 1, 8, 2, 9, 3, 6],
+    [5, 5, 5, 5, 5, 5, 5, 5],
+    [6, 3, 9, 2, 8, 1, 7, 4],
+    [7, 8, 4, 9, 1, 6, 2, 3],
+    [8, 9, 7, 6, 4, 3, 1, 2],
+    [9, 6, 8, 3, 7, 2, 4, 1],
+    [0, 0, 0, 0, 0, 0, 0, 0],
+    [1, 2, 4, 3, 7, 6, 8, 9],
+    [2, 3, 1, 6, 4, 9, 7, 8],
+    [3, 6, 2, 9, 1, 8, 4, 7],
+    [4, 1, 7, 2, 8, 3, 9, 6],
+    [5, 5, 5, 5, 5, 5, 5, 5],
+    [6, 9, 3, 8, 2, 7, 1, 4],
+    [7, 4, 8, 1, 9, 2, 6, 3],
+    [8, 7, 9, 4, 6, 1, 3, 2],
+    [9, 8, 6, 7, 3, 4, 2, 1],
+];
+//# sourceMappingURL=loc.js.map

package/dist/loc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loc.js","sourceRoot":"","sources":["../src/loc.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,4BAA4B;AAC5B,MAAM,UAAU,GAAG,CAAC,CAAS,EAAE,CAAS;IACtC,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AAClB,CAAC;AAED,8BAA8B;AAC9B,MAAM,UAAU,KAAK,CAAC,CAAM,EAAE,CAAM;IAClC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,mBAAmB;AACnB,MAAM,UAAU,SAAS,CAAC,CAAM;IAC9B,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED,eAAe;AACf,MAAM,UAAU,MAAM,CAAC,CAAM,EAAE,CAAM;IACnC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACnC,CAAC;AAED,uBAAuB;AACvB,MAAM,UAAU,OAAO,CAAC,CAAM,EAAE,CAAM;IACpC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACnC,CAAC;AAED,kBAAkB;AAClB,MAAM,UAAU,SAAS,CAAC,CAAM,EAAE,EAAU,EAAE,EAAU;IACtD,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;AACjC,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,OAAO,CACrB,GAAQ,EACR,IAAS,EACT,OAAe,EACf,OAAe;IAEf,OAAO,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,CAAM,EAAE,CAAM;IACrC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,GAAG,GAAsB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAElE,0DAA0D;AAC1D,MAAM,CAAC,MAAM,GAAG,GAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAExE,0DAA0D;AAC1D,MAAM,CAAC,MAAM,GAAG,GAAsB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAExE,+DAA+D;AAC/D,MAAM,CAAC,MAAM,MAAM,GAAmB;IACpC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACd,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACf,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACd,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACd,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACf,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACd,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACd,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IAChB,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IACf,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;CAChB,CAAC;AAEF,uCAAuC;AACvC,MAAM,CAAC,MAAM,OAAO,GAAsB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAEzE,uCAAuC;AACvC,MAAM,CAAC,MAAM,OAAO,GAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAEzE,4CAA4C;AAC5C,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACd,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IACf,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACd,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACf,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACd,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACf,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IACf,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IAChB,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;CACf,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAsB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAE5E,qEAAqE;AACrE,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IACf,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IACf,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACd,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACd,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACd,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACf,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IACf,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IAChB,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;CACf,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAmC;IACvD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;CACzB,CAAC"}

package/dist/mod/hooks.d.ts

@@ -0,0 +1,204 @@
+/**
+ * The behaviour seam: the closed set of points where a mod may change what the
+ * ENGINE does, as opposed to what content it runs on.
+ *
+ * WHY THIS EXISTS
+ *
+ * Content mods are already fully expressible - a pack contributes records and
+ * composeContentPacks merges them, and core never learns a mod was involved.
+ * Behaviour is different. A fix like "don't log a duplicate unique kill" is not a
+ * record; it is a decision taken inside a function, and no amount of data can
+ * reach inside that function from outside. So the first cut of the bundled
+ * bug-fixes / QoL mods did the only thing that was available: the FIX LIVED IN
+ * CORE behind `if (modRuleEnabled(state, "bugfix.x"))`.
+ *
+ * That was wrong, and neostryder named exactly why (2026-07-29): "the whole point of
+ * making them mods was to exclude them from the core game." A flag-gated fix is
+ * not excluded from core. It ships in core, it is tested in core, and core
+ * carries the string "bugfix.uniqueKillHistory" - so core knows the mod's name.
+ * Deleting the mod folder would not delete one line of it.
+ *
+ * WHAT THIS CHANGES, AND WHAT IT HONESTLY DOES NOT
+ *
+ * After this, core contains no mod's fix and no mod's name: no `bugfix.*` or
+ * `qol.*` literal, no staircase repair, no message rewriter. Each fix body lives
+ * in its mod's own folder and arrives as that mod's code.
+ *
+ * What core still contains - and cannot stop containing - is the SEAM ITSELF:
+ * one named, documented extension point per behaviour a mod may override. That
+ * is not a residue of the bundled mods; it is the price of behaviour modding at
+ * all, and it is the same bargain SKSE, Forge and every other real modding
+ * system strikes. The difference from a flag read is the difference that matters:
+ * a seam is generic and available to ANY mod, and it holds no opinion about what
+ * should plug into it, whereas `if (modRuleEnabled(state, "bugfix.stairsReachable"))`
+ * is core implementing one specific mod.
+ *
+ * SHAPE
+ *
+ * A plain interface of optional functions rather than a string-keyed registry,
+ * for three reasons:
+ *
+ *  - It is typed end to end. A registry keyed by strings pushes every payload
+ *    through `unknown` and moves the errors to runtime.
+ *  - "A disabled mod's patches DO NOT EXIST" becomes literally true, not merely
+ *    false-y: with no mod loaded the field is ABSENT, the optional call is not
+ *    made, and the faithful path is the only path that was ever compiled into
+ *    the branch. No flag map is consulted because there is no flag map.
+ *  - It costs nothing. `state.modHooks?.historyAdd?.(...)` on an absent object is
+ *    one undefined check, not a map lookup per call.
+ *
+ * COMPOSITION IS THE HOST'S JOB
+ *
+ * Two enabled mods may both want the same hook. Core deliberately holds ONE
+ * ModHooks and knows nothing about mod identity, ordering or enablement - the
+ * host (web/cli) collects each enabled mod's contributions in load order and
+ * folds them into a single object (see composeModHooks). This is the same
+ * layering as content: core consumes a composed result and never the pack list.
+ *
+ * DETERMINISM
+ *
+ * Two of these run inside the generation and object pipelines, where an extra
+ * RNG draw does not merely change a value, it desynchronises every draw after
+ * it - so a seed would stop meaning the same level. Those hooks are documented
+ * RNG-FREE and are given no rng to draw from. That is a contract a mod can still
+ * break by reaching for a global; the test suite pins it by running generation
+ * with a hook installed and asserting the level is bit-identical.
+ */
+import type { GameState } from "../game/context.js";
+/**
+ * A mod's behaviour contributions. Every member is optional; an absent member
+ * means "this mod does not touch that point" and core takes its faithful path.
+ *
+ * Each entry documents the ONE core call site it serves, because a hook whose
+ * call site is not written down is a hook nobody can verify is still wired -
+ * exactly the failure the call-site census exists to catch.
+ */
+export interface ModHooks {
+    /**
+     * A walk into a grid the player could tunnel through (cave-cmd.ts,
+     * movementAutoDig's call site).
+     *
+     * Return the energy the move should cost, or null to decline - and declining
+     * MUST be free of observable effect, because faithful core's behaviour here is
+     * to bump into the wall without drawing any RNG. A hook that rolls a dig check
+     * and then returns null has already moved the RNG stream.
+     *
+     * `deps` is the live CaveCmdDeps the session built, passed through because the
+     * work a mod would want to do here (tunnelAux - one real dig attempt with the
+     * upstream roll and payouts) needs dependencies only the session can construct.
+     * Typed as unknown so this seam does not drag the cave-command types into every
+     * consumer of ModHooks; a mod casts it back to CaveCmdDeps, which core exports.
+     *
+     * Serves: the QoL mod's "auto-dig on walk".
+     */
+    walkBlockedByDiggable?: (state: GameState, grid: {
+        y: number;
+        x: number;
+    }, deps: unknown) => number | null;
+    /**
+     * Two floor-list entries that compared exactly equal, including on distance
+     * (obj-list.ts, the comparator's final tiebreak).
+     *
+     * Return a negative/positive number to order them, or 0 to leave them equal
+     * (which is what faithful core does - it keeps collect order via a stable
+     * sort). Must be a consistent total order or the sort is meaningless.
+     *
+     * Serves: the bug-fixes mod's strict object-list ordering (#4664).
+     */
+    objectListTiebreak?: (a: {
+        readonly dy: number;
+        readonly dx: number;
+    }, b: {
+        readonly dy: number;
+        readonly dx: number;
+    }) => number;
+    /**
+     * A finished, otherwise-accepted level, before cave_generate returns it
+     * (generate.ts, the accept branch).
+     *
+     * Return false to REJECT the level, which makes cave_generate re-roll exactly
+     * as it does for a monster-maximum overflow. May mutate the level to repair it
+     * and then return true.
+     *
+     * RNG-FREE: no rng is passed and none may be reached. A draw here shifts every
+     * subsequent draw and a seed stops reproducing its dungeon.
+     *
+     * Serves: the bug-fixes mod's reachable-staircase repair.
+     */
+    levelGenerated?: (gen: unknown, quest: boolean) => boolean;
+    /**
+     * An object about to be committed as an artifact, when it ALREADY carries one
+     * (obj/make.ts, the `obj.artifact` branch).
+     *
+     * Return false to refuse the commit; the caller then clears the artifact and
+     * reports failure. Faithful core commits it unconditionally.
+     *
+     * RNG-FREE, for the same reason as levelGenerated: this runs inside object
+     * creation, on the main stream.
+     *
+     * Serves: the bug-fixes mod's duplicate-artifact guard (#4510).
+     */
+    artifactCommit?: (aidx: number, alreadyCreated: boolean) => boolean;
+    /**
+     * A character-history entry about to be written (session/game.ts and any
+     * other historyAdd call site that passes its context).
+     *
+     * Return false to suppress the entry. Faithful core writes every entry it
+     * reaches, duplicates included.
+     *
+     * Serves: the bug-fixes mod's no-duplicate-unique-kill fix (#4245).
+     */
+    historyAdd?: (entry: {
+        readonly what: string;
+        readonly type: number;
+        readonly duplicate: boolean;
+    }) => boolean;
+    /**
+     * Whether the noise and scent heatmaps belong in the save (session/save.ts,
+     * snapshotSquares' argument).
+     *
+     * Return true to persist them. Faithful core omits them, which is the upstream
+     * behaviour and the upstream bug.
+     *
+     * Serves: the bug-fixes mod's noise/scent persistence (#4605).
+     */
+    saveNoiseScent?: () => boolean;
+    /**
+     * Player-visible message text, on its way to the message line (the host's
+     * message sink).
+     *
+     * Return the text to show. Faithful core shows what it was given, warts and
+     * all. A hook here can only RESTATE a message - it must never change what a
+     * message means, or the port would be showing text upstream never wrote and no
+     * census could see it.
+     *
+     * Serves: the bug-fixes mod's cosmetic string corrections.
+     */
+    messageText?: (raw: string) => string;
+}
+/**
+ * Fold several mods' contributions into the single ModHooks core holds.
+ *
+ * Order is LOAD order, and what "later wins" means differs per hook because the
+ * hooks differ in kind - which is precisely why this is one written-down function
+ * and not a generic merge:
+ *
+ *  - VETO hooks (levelGenerated, artifactCommit, historyAdd) are conjunctive:
+ *    every contributor must agree, and the first refusal decides. This is the
+ *    only safe fold - a mod that vetoes a duplicate artifact must not be
+ *    overruled by a later mod that merely has no opinion.
+ *  - TRANSFORM hooks (messageText) compose in order, each seeing the previous
+ *    one's output.
+ *  - FIRST-HANDLER hooks (walkBlockedByDiggable) stop at the first non-null, so
+ *    an earlier mod's handling wins and a later one cannot double-spend energy.
+ *  - ANY hooks (saveNoiseScent) are disjunctive: one mod asking for the data is
+ *    enough, because the data is additive and a second mod cannot object.
+ *  - ORDERING hooks (objectListTiebreak) stop at the first non-zero answer, the
+ *    same way a lexicographic comparator chains.
+ *
+ * Returns undefined when nothing contributed, so the caller can leave the field
+ * absent rather than storing an empty object - keeping "no mod loaded" and "a
+ * mod loaded that touches nothing" indistinguishable from core's side.
+ */
+export declare function composeModHooks(contributions: readonly ModHooks[]): ModHooks | undefined;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/mod/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/mod/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;;;;;;;;;;;;OAgBG;IACH,qBAAqB,CAAC,EAAE,CACtB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAC9B,IAAI,EAAE,OAAO,KACV,MAAM,GAAG,IAAI,CAAC;IAEnB;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,CACnB,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAC/C,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,KAC5C,MAAM,CAAC;IAEZ;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAE3D;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,KAAK,OAAO,CAAC;IAEpE;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC;IAE/G;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC;IAE/B;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,SAAS,QAAQ,EAAE,GACjC,QAAQ,GAAG,SAAS,CAkEtB"}