Add the interface, then rebuild the economy around the first playtest

The MVP is playable: a turn screen, a career retrospective, an optional
feedback widget, local-storage autosave with file export/import, and a build
that flattens everything into one self-contained HTML file.

A turn has two phases — the scenario and its options, then what the choice did
and, separately, what the day cost regardless. Numbers that move without the
player seeing why are most of what makes them meaningless. Locked options are
shown greyed with the requirement spelled out rather than hidden, so a player
can see the door they cannot open yet.

The interface is named entirely by the pack. `pack.display` maps a state path to
a label, a format and an order, which is why the header reads "Standing" for a
path called `reputation` and why debt disappears while it is zero.

The first playtest then found three things, all of them fair.

*"Wasn't clear what daily drain was for."* The ledger was labelling changes by
the path that moved — "Money −$18" — when the upkeep entry that caused them had
a perfectly good name. It now says "Coffee, transit, lunch". The labels were in
the data the whole time and never reached the screen.

*"Should probably pay rent weekly / get paid every other week… would be good to
have day of week and week # shown."* Packs can now declare a calendar, and the
engine derives the day name, cycle and index from the turn number before the
event is drawn — so content can require a Friday and the header can say
"Thursday · Week 2 · Day 12". Upkeep entries take `every` and `offset`, making
wages fall on alternate Fridays and rent every Monday. The turn screen carries
a diary line — "Wages tomorrow · Rent in 4 days" — computed generically from
whatever a pack schedules.

*"Always in debt — could never get ahead."* The old economy bled $25 a day
regardless of play. It is now roughly break-even at baseline, with a
`spare_shift` event that appears *because* you are broke: the way out of a hole
should be visible from inside it. Across archetypes a careful player ends around
$1,400, an unplanned one treads water, and a careless one sinks into real debt.

That retune broke the coverage test, usefully. Random play stopped reaching hard
times at all, which made the entire debt branch look dead — it was not, since
random play is not a plausible player. Coverage is now the union across five
archetypes, including one that is broke *and* well-liked, because the "ask a
friend for money" options sit in a state no single-axis strategy reaches.

Not covered by any of this: styling and dark mode, which only a human with a
browser can check. This machine has none that can render a page.

109 tests. Reasoning in docs/DECISIONS.md §14-21.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VMSFHyVPitUoosW5wyEADj

src/engine/game.js

@@ -17,19 +17,53 @@ export class MoveError extends Error {}
 
 /** Draw the next event and record where the generator ended up. */
 function advance(pack, state) {
-  const rng = createRng(state.meta.seed, state.meta.rngPosition ?? undefined);
-  const event = selectEvent(pack, state, rng);
+  // The calendar is settled before the draw, so an event can require a Friday.
+  const dated = applyCalendar(pack, state);
+  const rng = createRng(dated.meta.seed, dated.meta.rngPosition ?? undefined);
+  const event = selectEvent(pack, dated, rng);
   if (!event) {
     throw new ContentError(
-      `no event is eligible at stage "${state.stage}" on turn ${state.turn}; ` +
+      `no event is eligible at stage "${dated.stage}" on turn ${dated.turn}; ` +
       'every stage needs at least one event with no conditions',
     );
   }
-  let next = setPath(state, 'meta.currentEventId', event.id);
+  let next = setPath(dated, 'meta.currentEventId', event.id);
   next = setPath(next, 'meta.rngPosition', rng.getPosition());
   return next;
 }
 
+/**
+ * Derive the calendar from the turn number.
+ *
+ * A pack that declares `calendar` gets `calendar.index` (position in the
+ * cycle), `calendar.cycle` (which cycle, 1-based) and `calendar.name` written
+ * into engine-owned state before the turn's event is chosen — so content can
+ * gate on the day of the week, and upkeep can charge rent on one of them. A
+ * pack that declares no calendar simply has none; the engine imposes no week.
+ */
+function applyCalendar(pack, state) {
+  const calendar = pack.calendar;
+  if (!calendar?.cycleLength) return state;
+
+  const elapsed = state.turn - 1;
+  const index = ((elapsed % calendar.cycleLength) + calendar.cycleLength) % calendar.cycleLength;
+  let next = setPath(state, 'calendar.index', index);
+  next = setPath(next, 'calendar.cycle', Math.floor(elapsed / calendar.cycleLength) + 1);
+  return setPath(next, 'calendar.name', calendar.unitNames?.[index] ?? null);
+}
+
+/**
+ * Whether a scheduled upkeep entry falls due this turn. `every` is a period in
+ * turns and `offset` the first turn it lands on (zero-based), so wages every
+ * fortnight starting on the seventh day are `{ every: 14, offset: 6 }`. An
+ * entry with no `every` runs every turn.
+ */
+function isDue(entry, state) {
+  if (!entry.every) return true;
+  const elapsed = state.turn - 1 - (entry.offset ?? 0);
+  return elapsed >= 0 && elapsed % entry.every === 0;
+}
+
 /**
  * Apply the pack's per-turn upkeep — wages in, rent out, whatever a loan
  * costs to carry. Each entry may carry its own conditions, evaluated after the
@@ -40,6 +74,7 @@ function applyUpkeep(pack, state, schema) {
   let next = state;
   const changes = [];
   for (const entry of pack.upkeep ?? []) {
+    if (!isDue(entry, next)) continue;
     if (!check(next, entry.requires).passed) continue;
     const applied = applyEffects(next, entry.effects, schema);
     next = applied.state;

src/engine/state.js

@@ -11,7 +11,8 @@ import { setPath } from './paths.js';
  * day 10", "only if this event hasn't fired" — but may not declare or write
  * them, which is what keeps engine bookkeeping from being corrupted by data.
  */
-export const RESERVED_ROOTS = new Set(['turn', 'stage', 'seen', 'lastSeen', 'history', 'meta']);
+export const RESERVED_ROOTS =
+  new Set(['turn', 'stage', 'seen', 'lastSeen', 'history', 'meta', 'calendar']);
 
 /**
  * Flatten a pack's state declarations into one path -> rule map, expanding the
@@ -51,6 +52,7 @@ export function createState(pack, { seed, schema = resolveSchema(pack) } = {}) {
     stage: pack.startingStage,
     seen: {},
     lastSeen: {},
+    calendar: {},
     history: [],
   };
   for (const [path, rule] of Object.entries(schema)) {

src/engine/validate.js

@@ -95,8 +95,27 @@ export function validatePack(pack) {
     list.forEach(walk);
   };
 
+  if (pack.calendar) {
+    const { cycleLength, unitNames } = pack.calendar;
+    if (!Number.isInteger(cycleLength) || cycleLength < 1) {
+      fail('calendar', `cycleLength ${cycleLength} must be a positive whole number`);
+    }
+    if (unitNames && unitNames.length !== cycleLength) {
+      fail('calendar', `unitNames has ${unitNames.length} entries but cycleLength is ${cycleLength}`);
+    }
+  }
+
   (pack.upkeep ?? []).forEach((entry, index) => {
     const where = `upkeep[${index}]${entry.label ? ` "${entry.label}"` : ''}`;
+    if (entry.every !== undefined && (!Number.isInteger(entry.every) || entry.every < 1)) {
+      fail(where, `every ${entry.every} must be a positive whole number of turns`);
+    }
+    if (entry.offset !== undefined && (!Number.isInteger(entry.offset) || entry.offset < 0)) {
+      fail(where, `offset ${entry.offset} must be zero or a positive whole number`);
+    }
+    if (entry.offset !== undefined && entry.every === undefined) {
+      warn(where, 'offset has no effect without every');
+    }
     checkConditions(where, entry.requires);
     if (!entry.effects?.length) fail(where, 'has no effects');
     for (const effect of entry.effects ?? []) {