diff options
49 files changed, 190 insertions, 220 deletions
diff --git a/app/app.d.ts b/app/app.d.ts index a59afa2..242ec56 100644 --- a/app/app.d.ts +++ b/app/app.d.ts @@ -1,13 +1,6 @@ -// See https://svelte.dev/docs/kit/types#app.d.ts for details on these types. -// Populate App interfaces as systems come online. declare global { namespace App { - // interface Error {} - // interface Locals {} - // interface PageData {} - // interface PageState {} - // interface Platform {} } } diff --git a/engine/career/career.ts b/engine/career/career.ts index aa19584..e8a5af2 100644 --- a/engine/career/career.ts +++ b/engine/career/career.ts @@ -1,5 +1,5 @@ import type { GameTime } from '@hollowdark/time/gameTime' -import type { InstitutionId } from '../entities/base' +import type { InstitutionId } from '@hollowdark/engine/entities/base' export type CareerTrajectory = 'rising' | 'steady' | 'declining' | 'stalled' diff --git a/engine/economics/affordability.ts b/engine/economics/affordability.ts index ef57d3f..827ccd8 100644 --- a/engine/economics/affordability.ts +++ b/engine/economics/affordability.ts @@ -1,8 +1,7 @@ /** * The "What you could afford" surface on the Money screen. Hidden numbers * resolve into qualitative feasibility labels so the player answers - * "can I afford this?" without ever seeing a number (docs/09-economy.md - * §"The 'What you could afford' design"). + * "can I afford this?" without ever seeing a number. */ export type Feasibility = | 'comfortable' diff --git a/engine/economics/economic.ts b/engine/economics/economic.ts index 1197cde..2d37ced 100644 --- a/engine/economics/economic.ts +++ b/engine/economics/economic.ts @@ -1,9 +1,8 @@ /** - * Economic state. All numbers in "marks" (the world's universal currency). - * The player never sees any of these — they surface as prose and qualitative - * affordability context (docs/09-economy.md, ARCHITECTURE.md §14). + * A coarse wealth tier derived from the hidden economic state. Never + * displayed numerically; informs surface prose ("struggling", "comfortable", + * "old money"). */ - export type EconomicClass = | 'destitute' | 'struggling' @@ -44,6 +43,11 @@ export interface Debt { readonly apr: number } +/** + * Hidden economic state for a character. All numbers are in "marks" (the + * world's universal currency). Never surfaced to the player as digits — + * the simulation drives prose and qualitative affordability context. + */ export interface EconomicState { readonly cashOnHand: number readonly accounts: readonly Account[] diff --git a/engine/entities/base.ts b/engine/entities/base.ts index 84b9acf..c1cf6d8 100644 --- a/engine/entities/base.ts +++ b/engine/entities/base.ts @@ -4,7 +4,6 @@ import type { Brand } from '@hollowdark/utils/types/brand' /** * Branded IDs — string at runtime, distinct at compile time so a PersonId * can't silently flow into a slot that expects a RelationshipId. - * (utils/types/brand.ts) */ export type PersonId = Brand<string, 'PersonId'> export type RelationshipId = Brand<string, 'RelationshipId'> @@ -26,7 +25,6 @@ export type EntityKind = 'person' | 'relationship' | 'institution' | 'place' | ' * their specific id/kind pair — `Person extends BaseEntity<PersonId, 'person'>`. * `deterministicSeed` powers lazy Tier 3 regeneration: given the seed, the * entity's trajectory is fully reproducible without persisted state. - * (ARCHITECTURE.md §26) */ export interface BaseEntity<Id extends string = string, K extends EntityKind = EntityKind> { readonly id: Id diff --git a/engine/entities/event-log-entry.ts b/engine/entities/event-log-entry.ts index f31536d..1e107f4 100644 --- a/engine/entities/event-log-entry.ts +++ b/engine/entities/event-log-entry.ts @@ -1,5 +1,5 @@ import type { GameTime } from '@hollowdark/time/gameTime' -import type { EventLogEntryId, PersonId } from './base' +import type { EventLogEntryId, PersonId } from '@hollowdark/engine/entities/base' /** * Consequences logged against a specific event resolution. The shape is diff --git a/engine/entities/flow-entry.ts b/engine/entities/flow-entry.ts index bd781d5..ba2b11a 100644 --- a/engine/entities/flow-entry.ts +++ b/engine/entities/flow-entry.ts @@ -1,5 +1,5 @@ import type { GameTime } from '@hollowdark/time/gameTime' -import type { FlowEntryId, PersonId, PlaceId, WorldEventId } from './base' +import type { FlowEntryId, PersonId, PlaceId, WorldEventId } from '@hollowdark/engine/entities/base' /** * A compact snapshot of the context that produced a flow passage. Kept diff --git a/engine/entities/institution.ts b/engine/entities/institution.ts index 4b3c050..d89aac2 100644 --- a/engine/entities/institution.ts +++ b/engine/entities/institution.ts @@ -1,6 +1,6 @@ import type { GameTime } from '@hollowdark/time/gameTime' -import type { BaseEntity, InstitutionId, PersonId, PlaceId } from './base' -import type { CultureDescriptor } from './place' +import type { BaseEntity, InstitutionId, PersonId, PlaceId } from '@hollowdark/engine/entities/base' +import type { CultureDescriptor } from '@hollowdark/engine/entities/place' export type InstitutionType = | 'company' diff --git a/engine/entities/memoir.ts b/engine/entities/memoir.ts index c0f44f3..1f3f37f 100644 --- a/engine/entities/memoir.ts +++ b/engine/entities/memoir.ts @@ -1,5 +1,5 @@ import type { GameTime } from '@hollowdark/time/gameTime' -import type { EventLogEntryId, MemoirId, PersonId } from './base' +import type { EventLogEntryId, MemoirId, PersonId } from '@hollowdark/engine/entities/base' export interface MemoirChapter { readonly order: number @@ -12,9 +12,10 @@ export interface MemoirChapter { } /** - * Generated at character death. 15,000–30,000 words, 8–15 chapters. Persists - * forever in the world's archive; descendants may find it on the Memoirs - * shelf or referenced in flow (docs/14-memoirs.md, ARCHITECTURE.md §17). + * A character's generated life story. Produced at death, 15,000–30,000 + * words across 8–15 chapters. Persists forever in the world's archive; + * descendants may find it on the Memoirs shelf or see it referenced in + * their own flow. */ export interface Memoir { readonly id: MemoirId diff --git a/engine/entities/person-name.ts b/engine/entities/person-name.ts index 5f84b41..8c234dc 100644 --- a/engine/entities/person-name.ts +++ b/engine/entities/person-name.ts @@ -1,8 +1,8 @@ /** * A character's name as tracked by the simulation. Surnames follow - * inheritance rules per region/era (docs/19-names.md) — including keep- - * maiden, hyphenate, matrilineal, and ad-hoc changes — so the structure - * preserves both the current surname and the maiden form when relevant. + * inheritance rules per region and era — including keep-maiden, hyphenate, + * matrilineal, and ad-hoc changes — so the structure preserves both the + * current surname and the maiden form when relevant. */ export interface PersonName { readonly given: string diff --git a/engine/entities/person.ts b/engine/entities/person.ts index beabede..1dc28a1 100644 --- a/engine/entities/person.ts +++ b/engine/entities/person.ts @@ -1,26 +1,26 @@ import type { GameTime } from '@hollowdark/time/gameTime' -import type { CareerState } from '../career/career' -import type { EconomicState } from '../economics/economic' -import type { Condition, HealthState } from '../health/health' -import type { MentalHealthState } from '../health/mental-health' -import type { Dependency } from '../state/dependency' -import type { MoodState } from '../state/mood' -import type { SatisfactionProfile } from '../state/satisfaction' -import type { Scar } from '../state/scar' -import type { AttachmentDistribution } from '../traits/attachment' -import type { BigFiveProfile } from '../traits/big-five' -import type { CoreBeliefs } from '../traits/core-beliefs' -import type { DarkTriadProfile } from '../traits/dark-triad' -import type { SexualOrientation } from '../traits/orientation' -import type { ValuesOrientation } from '../traits/values' -import type { BaseEntity, PersonId, PlaceId, RelationshipId } from './base' -import type { EventLogEntry } from './event-log-entry' -import type { PersonName } from './person-name' -import type { ReputationProfile } from './reputation' -import type { ResidenceEntry } from './residence' -import type { StatusDescriptor } from './status' - -/** Modes of death per docs/20-death-textures.md. */ +import type { CareerState } from '@hollowdark/engine/career/career' +import type { EconomicState } from '@hollowdark/engine/economics/economic' +import type { Condition, HealthState } from '@hollowdark/engine/health/health' +import type { MentalHealthState } from '@hollowdark/engine/health/mental-health' +import type { Dependency } from '@hollowdark/engine/state/dependency' +import type { MoodState } from '@hollowdark/engine/state/mood' +import type { SatisfactionProfile } from '@hollowdark/engine/state/satisfaction' +import type { Scar } from '@hollowdark/engine/state/scar' +import type { AttachmentDistribution } from '@hollowdark/engine/traits/attachment' +import type { BigFiveProfile } from '@hollowdark/engine/traits/big-five' +import type { CoreBeliefs } from '@hollowdark/engine/traits/core-beliefs' +import type { DarkTriadProfile } from '@hollowdark/engine/traits/dark-triad' +import type { SexualOrientation } from '@hollowdark/engine/traits/orientation' +import type { ValuesOrientation } from '@hollowdark/engine/traits/values' +import type { BaseEntity, PersonId, PlaceId, RelationshipId } from '@hollowdark/engine/entities/base' +import type { EventLogEntry } from '@hollowdark/engine/entities/event-log-entry' +import type { PersonName } from '@hollowdark/engine/entities/person-name' +import type { ReputationProfile } from '@hollowdark/engine/entities/reputation' +import type { ResidenceEntry } from '@hollowdark/engine/entities/residence' +import type { StatusDescriptor } from '@hollowdark/engine/entities/status' + +/** The ten modes of death the simulation can resolve. */ export type DeathMode = | 'expected_old_age' | 'sudden_accident' @@ -35,7 +35,7 @@ export type DeathMode = /** * The defining demographic facts of a birth, captured in prose-ready form. * The familyContext string is the one-paragraph summary the opening scene - * draws on (docs/17-first-hour.md §"Birth moment"). + * draws on. */ export interface BirthRecord { readonly date: GameTime @@ -51,15 +51,15 @@ export interface DeathRecord { } /** - * NPC simulation fidelity tier. 1 = full weekly simulation (~10-30 entities), - * 2 = quarterly compressed, 3 = generated on demand from seed. - * See docs/06-autonomy.md §"Tiered simulation fidelity". + * NPC simulation fidelity tier. 1 = full weekly simulation (~10–30 + * close-orbit entities), 2 = quarterly compressed (dormant relatives, + * drifted friends), 3 = generated on demand from seed (everyone else). */ export type SimulationTier = 1 | 2 | 3 /** * Person — the main simulated entity. Players and NPCs share this shape. - * Fields are grouped by trait layer (docs/04-traits.md): + * Fields are grouped by trait layer: * * Layer 1 temperament (Big Five + Dark Triad) — mostly stable * Layer 2 developmental (attachment, core beliefs, values, orientation) @@ -75,65 +75,52 @@ export interface Person extends BaseEntity<PersonId, 'person'> { readonly birth: BirthRecord readonly death: DeathRecord | null - // Layer 1 — temperament readonly bigFive: BigFiveProfile readonly darkTriad: DarkTriadProfile - // Layer 2 — developmental readonly attachment: AttachmentDistribution readonly coreBeliefs: CoreBeliefs readonly conscienceCapacity: number readonly values: ValuesOrientation readonly orientation: SexualOrientation - // Layer 3 — fluctuating state readonly mood: MoodState readonly stress: number readonly energy: number readonly traumaLoad: number readonly satisfaction: SatisfactionProfile - // Layer 4 — acquired readonly skills: ReadonlyMap<string, number> readonly knowledge: ReadonlyMap<string, number> readonly habits: readonly string[] readonly dependencies: readonly Dependency[] readonly scars: readonly Scar[] - // Layer 5 — social readonly reputation: ReputationProfile readonly status: StatusDescriptor readonly networkCapital: number - // Health readonly health: HealthState readonly chronicConditions: readonly Condition[] readonly mentalHealthState: MentalHealthState - // Economic / career readonly economic: EconomicState readonly career: CareerState - // Relationships + location readonly relationshipIds: readonly RelationshipId[] readonly currentPlaceId: PlaceId readonly residenceHistory: readonly ResidenceEntry[] - // Simulation metadata readonly tier: SimulationTier readonly lastSimulatedAt: GameTime - // Event history readonly eventLog: readonly EventLogEntry[] readonly memorableMoments: readonly string[] - // Player-character flags readonly isPlayerCharacter: boolean readonly playerCharacterStartedAt: GameTime | null readonly playerCharacterEndedAt: GameTime | null - // Family (denormalised for fast access; the authoritative source is the - // Relationship entities keyed family_parent / family_child / family_spouse) readonly parentIds: readonly [PersonId | null, PersonId | null] readonly childIds: readonly PersonId[] readonly spouseIds: readonly PersonId[] diff --git a/engine/entities/place.ts b/engine/entities/place.ts index 2a38c41..8ec1f9b 100644 --- a/engine/entities/place.ts +++ b/engine/entities/place.ts @@ -1,4 +1,4 @@ -import type { BaseEntity, PersonId, PlaceId } from './base' +import type { BaseEntity, PersonId, PlaceId } from '@hollowdark/engine/entities/base' export type PlaceType = 'region' | 'city' | 'neighborhood' | 'specific_location' @@ -40,7 +40,6 @@ export interface Place extends BaseEntity<PlaceId, 'place'> { readonly type: PlaceType readonly parentPlaceId: PlaceId | null - // Present for regions and cities; null for specific locations. readonly culture: CultureDescriptor | null readonly climate: ClimateDescriptor | null readonly economy: EconomicCharacter | null @@ -48,7 +47,6 @@ export interface Place extends BaseEntity<PlaceId, 'place'> { readonly population: number - // Present for specific locations (houses, workplaces); null for containers. readonly ownerId: PersonId | null readonly currentResidents: readonly PersonId[] readonly propertyValue: number | null diff --git a/engine/entities/relationship.ts b/engine/entities/relationship.ts index ec00007..2a7710b 100644 --- a/engine/entities/relationship.ts +++ b/engine/entities/relationship.ts @@ -1,5 +1,5 @@ import type { GameTime } from '@hollowdark/time/gameTime' -import type { BaseEntity, PersonId, RelationshipId } from './base' +import type { BaseEntity, PersonId, RelationshipId } from '@hollowdark/engine/entities/base' export type RelationType = | 'family_parent' @@ -30,10 +30,9 @@ export type RelationType = export type RelationshipState = 'warm' | 'neutral' | 'strained' | 'ruptured' | 'dormant' /** - * The four axes of intimacy (docs/07-relationships.md §"Relationship state - * vector"). Each 0–1. Tracked separately because a marriage can be high - * on practical and low on emotional — that's a specific life texture, not - * a compatibility score. + * The four axes of intimacy. Each 0–1. Tracked separately because a + * marriage can be high on practical and low on emotional — that's a + * specific life texture, not a compatibility score. */ export interface IntimacyAxes { readonly emotional: number @@ -88,9 +87,9 @@ export interface LoveLanguageMatrix { } /** - * Asymmetric perception: A and B each have their own mental model of the - * relationship. Large asymmetries fire scenes (confession, rebuff, shocked - * realisation). See docs/07-relationships.md §"Asymmetric perception". + * Asymmetric perception: A and B each carry their own mental model of the + * relationship. Large asymmetries fire scenes — confession, rebuff, + * shocked realisation. */ export interface RelationshipPerception { readonly perceivedType: RelationType @@ -162,15 +161,12 @@ export interface Relationship extends BaseEntity<RelationshipId, 'relationship'> readonly lastInteractionAt: GameTime readonly interactionFrequency: number - // Romantic-only details; null when the relationship isn't romantic. readonly romanticPhase: RomanticPhase | null readonly sexualActivity: SexualActivityState | null readonly infidelityHistory: readonly InfidelityEvent[] readonly commitmentLevel: number - // Family-only. readonly familyRelationType: FamilyRelation | null - // Professional-only. readonly workRelationType: WorkRelation | null } diff --git a/engine/entities/residence.ts b/engine/entities/residence.ts index a052c42..83ddce8 100644 --- a/engine/entities/residence.ts +++ b/engine/entities/residence.ts @@ -1,5 +1,5 @@ import type { GameTime } from '@hollowdark/time/gameTime' -import type { PlaceId } from './base' +import type { PlaceId } from '@hollowdark/engine/entities/base' /** A span of time a character lived at a specific place. Open-ended if the * character still lives there. */ diff --git a/engine/entities/routine.ts b/engine/entities/routine.ts index 251cbde..a7068c1 100644 --- a/engine/entities/routine.ts +++ b/engine/entities/routine.ts @@ -1,5 +1,5 @@ import type { GameTime } from '@hollowdark/time/gameTime' -import type { PersonId, RoutineId } from './base' +import type { PersonId, RoutineId } from '@hollowdark/engine/entities/base' export type RoutineCategory = 'work' | 'relationships' | 'self' | 'home' | 'play' | 'service' @@ -27,7 +27,7 @@ export interface RoutineItem { /** * Persistent weekly commitments for a character. Routines run silently in * the flow stream — the player sets them once, they keep running until - * changed (docs/05-time-system.md §"Routines and flow"). + * changed. */ export interface Routine { readonly id: RoutineId diff --git a/engine/entities/scheduled-event.ts b/engine/entities/scheduled-event.ts index 08be670..254e979 100644 --- a/engine/entities/scheduled-event.ts +++ b/engine/entities/scheduled-event.ts @@ -1,10 +1,10 @@ import type { GameTime } from '@hollowdark/time/gameTime' -import type { PersonId, ScheduledEventId } from './base' +import type { PersonId, ScheduledEventId } from '@hollowdark/engine/entities/base' /** * A future event trigger, either at a fixed time or when conditions hold. * Taking a bribe at 30 might schedule a `bribery_audit` at +15 years with - * elevated weight (ARCHITECTURE.md §6 §"Scheduled events"). + * elevated weight. */ export interface ConditionalTrigger { readonly kind: 'conditional' diff --git a/engine/entities/world-event.ts b/engine/entities/world-event.ts index 8b4e2a6..ca158cc 100644 --- a/engine/entities/world-event.ts +++ b/engine/entities/world-event.ts @@ -1,5 +1,5 @@ import type { GameTime } from '@hollowdark/time/gameTime' -import type { BaseEntity, PersonId, PlaceId, WorldEventId } from './base' +import type { BaseEntity, PersonId, PlaceId, WorldEventId } from '@hollowdark/engine/entities/base' export type EventCategory = | 'pandemic' @@ -17,8 +17,8 @@ export type EventCategory = export type SeverityLevel = 'mild' | 'moderate' | 'severe' | 'catastrophic' /** - * A named macro event decorating the timeline. See docs/02-world-events.md. - * The character-level impact of each event is applied per-person via + * A named macro event decorating the timeline — a pandemic, war, cultural + * shift, economic crash. Character-level impact is applied per-person via * templates referenced by contentRef; this entity is the world-scale record. */ export interface WorldEvent extends BaseEntity<WorldEventId, 'world_event'> { diff --git a/engine/entities/world.ts b/engine/entities/world.ts index 920fe05..8d0b328 100644 --- a/engine/entities/world.ts +++ b/engine/entities/world.ts @@ -1,11 +1,11 @@ import type { GameTime } from '@hollowdark/time/gameTime' -import type { PersonId, PlaceId, WorldEventId, WorldId } from './base' -import type { ScheduledEvent } from './scheduled-event' +import type { PersonId, PlaceId, WorldEventId, WorldId } from '@hollowdark/engine/entities/base' +import type { ScheduledEvent } from '@hollowdark/engine/entities/scheduled-event' /** - * Macro economic state tracked at the world scale. Individual characters' - * economics are derived against this background (docs/09-economy.md - * §"Macro economy"). + * Macro economic state tracked at the world scale — inflation, employment, + * market index, recession depth. Individual characters' economics derive + * against this background. */ export interface MacroEconomicState { readonly inflationAnnual: number @@ -33,14 +33,14 @@ export interface CrisisState { } /** - * The world container. One continuous world per player (ARCHITECTURE.md §16, - * docs/16-world-continuity.md). Time in this world never resets once - * created; successive player characters advance it forward. + * The world container. One continuous world per player. Time in this world + * never resets once created; successive player characters advance it forward. + * `createdAt` is a real-world ISO timestamp, not a `GameTime`. */ export interface World { readonly id: WorldId readonly seed: string - readonly createdAt: string // ISO timestamp, real-world clock — not a GameTime + readonly createdAt: string readonly currentGameTime: GameTime diff --git a/engine/health/health.ts b/engine/health/health.ts index e08433d..4c69d34 100644 --- a/engine/health/health.ts +++ b/engine/health/health.ts @@ -41,10 +41,9 @@ export interface Condition { } /** - * A condition the simulation tracks but the character doesn't yet know about. - * Surface paths include worsening symptoms, doctor visits, routine screens, - * or incidental discovery (docs/08-mental-health.md §"Suicide risk" for the - * comparable mental-health pattern; this covers physical equivalents). + * A condition the simulation tracks but the character doesn't yet know + * about. Surface paths include worsening symptoms, doctor visits, routine + * screens, or incidental discovery. */ export interface UndiagnosedCondition { readonly id: string diff --git a/engine/health/mental-health.ts b/engine/health/mental-health.ts index 7130177..2e54e71 100644 --- a/engine/health/mental-health.ts +++ b/engine/health/mental-health.ts @@ -48,7 +48,7 @@ export interface Medication { /** * Hidden even from the character until crisis. The simulation knows; the - * prose surfaces behaviour, not numbers (docs/08-mental-health.md §"Suicide"). + * prose surfaces behaviour, never numbers. */ export interface SuicidalRisk { readonly current: number diff --git a/engine/state/dependency.ts b/engine/state/dependency.ts index 47787da..e3aca72 100644 --- a/engine/state/dependency.ts +++ b/engine/state/dependency.ts @@ -1,8 +1,7 @@ import type { GameTime } from '@hollowdark/time/gameTime' /** - * A substance or behavioural dependency at a given stage of progression. - * Stages mirror docs/08-mental-health.md §"Addiction modeled honestly": + * A substance or behavioural dependency at a given stage of progression: * experimentation → regular use → problem use → dependence → crisis → * recovery | chronic | death. */ diff --git a/engine/state/mood.ts b/engine/state/mood.ts index 501a699..205b5ec 100644 --- a/engine/state/mood.ts +++ b/engine/state/mood.ts @@ -4,7 +4,6 @@ import type { GameTime } from '@hollowdark/time/gameTime' * Current-week emotional state on the valence × arousal plane. * valence -1 (negative) to +1 (positive) * arousal -1 (calm) to +1 (activated) - * See docs/08-mental-health.md §"Separate variables". */ export interface MoodState { readonly valence: number diff --git a/engine/state/satisfaction.ts b/engine/state/satisfaction.ts index a10421b..eae65ec 100644 --- a/engine/state/satisfaction.ts +++ b/engine/state/satisfaction.ts @@ -1,8 +1,7 @@ /** * Life satisfaction split into hedonic (day-to-day pleasure) and eudaimonic - * (sense of meaning / purpose). They can diverge, and eudaimonic matters - * more for end-of-life peace (docs/13-spirituality.md §"Life satisfaction - * is distinct from happiness"). Each 0–1. + * (sense of meaning / purpose). They can diverge; eudaimonic matters more + * for end-of-life peace. Each 0–1. */ export interface SatisfactionProfile { readonly hedonic: number diff --git a/engine/traits/attachment.ts b/engine/traits/attachment.ts index 7af4c1b..eae77fa 100644 --- a/engine/traits/attachment.ts +++ b/engine/traits/attachment.ts @@ -1,7 +1,7 @@ /** * Attachment is tracked as a distribution, not a single tag. Fractions sum * to 1.0; a character is rarely purely one style. Set by age 3 based on - * caregiver behaviour, mostly fixed thereafter (docs/04-traits.md §"Layer 2"). + * caregiver behaviour, mostly fixed thereafter. */ export interface AttachmentDistribution { readonly secure: number diff --git a/engine/traits/big-five.ts b/engine/traits/big-five.ts index 425c91c..dbf5bd7 100644 --- a/engine/traits/big-five.ts +++ b/engine/traits/big-five.ts @@ -1,6 +1,6 @@ /** - * Big Five temperament profile, each 0–100. Mostly stable across a life - * with slow drift under sustained conditions. See docs/04-traits.md §"Layer 1". + * Big Five temperament profile. Each axis is 0–100, mostly stable across + * a life with slow drift under sustained conditions. */ export interface BigFiveProfile { readonly openness: number diff --git a/engine/traits/core-beliefs.ts b/engine/traits/core-beliefs.ts index 4e3b85a..f35daa0 100644 --- a/engine/traits/core-beliefs.ts +++ b/engine/traits/core-beliefs.ts @@ -1,6 +1,6 @@ /** - * Core beliefs shape how adult events are interpreted (docs/04-traits.md - * §"Layer 2"). Each 0–100. Formed in early childhood, harder to shift after. + * Core beliefs shape how adult events are interpreted. Each axis is 0–100, + * formed in early childhood and harder to shift after. */ export interface CoreBeliefs { readonly selfWorth: number diff --git a/engine/traits/dark-triad.ts b/engine/traits/dark-triad.ts index e8e1450..fff49c5 100644 --- a/engine/traits/dark-triad.ts +++ b/engine/traits/dark-triad.ts @@ -1,7 +1,7 @@ /** - * Dark Triad profile, each 0–100. Distribution is skewed low — most - * characters sit in the 20–40 range; a small minority above 60 drives - * specific life shapes (docs/04-traits.md §"Dark Triad characters in play"). + * Dark Triad profile. Each axis is 0–100. Distribution in the simulation + * skews low — most characters sit in the 20–40 range; a small minority + * above 60 drives specific life shapes. */ export interface DarkTriadProfile { readonly narcissism: number diff --git a/engine/traits/orientation.ts b/engine/traits/orientation.ts index 60decd9..e72a9cf 100644 --- a/engine/traits/orientation.ts +++ b/engine/traits/orientation.ts @@ -1,6 +1,6 @@ /** * Gender identity and sexual orientation. Continuous axes plus a discrete - * gender tag. See docs/04-traits.md §"Layer 2" and docs/10-sexuality.md. + * gender tag. * * sexualAttraction 0 = hetero-exclusive, 100 = homo-exclusive * romanticAttraction independent continuous axis diff --git a/engine/traits/values.ts b/engine/traits/values.ts index 0d67d16..83ae529 100644 --- a/engine/traits/values.ts +++ b/engine/traits/values.ts @@ -1,7 +1,7 @@ /** * Values orientation. Each axis is 0–100 where 0 anchors the left-named - * pole and 100 the right (e.g., tradition_vs_novelty: 0 = deeply traditional, - * 100 = novelty-seeking). See docs/04-traits.md §"Layer 2". + * pole and 100 the right (e.g., `tradition_vs_novelty`: 0 = deeply + * traditional, 100 = novelty-seeking). */ export interface ValuesOrientation { readonly tradition_vs_novelty: number diff --git a/hooks/client.ts b/hooks/client.ts index b65ecdc..844ac2c 100644 --- a/hooks/client.ts +++ b/hooks/client.ts @@ -1,9 +1,5 @@ -// Client-side setup runs once when the app mounts. -// Later: service worker registration, audio unlock on first gesture, -// persistent-storage request, IndexedDB hydration. Empty for now. import type { ClientInit } from '@sveltejs/kit' export const init: ClientInit = async () => { - // Intentionally empty. Systems attach here as they come online. } diff --git a/persistence/db.ts b/persistence/db.ts index 213e19b..d8647b0 100644 --- a/persistence/db.ts +++ b/persistence/db.ts @@ -20,7 +20,7 @@ import { CONTENT_CACHE_SCHEMA_V1, USER_DATA_DB_NAME, USER_DATA_SCHEMA_V1 -} from './schema' +} from '@hollowdark/persistence/schema' /** * A single key/value pair on the Settings table. Keys are short slugs @@ -62,8 +62,8 @@ export interface CachedAudioTrack { /** * User save data — the player's world(s). Persists forever on device, - * untouched by content updates (technical/04-persistence.md §"Core - * decisions"). Changes to this schema require a migration. + * untouched by content updates. Changes to this schema require a + * migration in `persistence/migrations` (added later). */ export class HollowdarkUserData extends Dexie { worlds!: Table<World, string> @@ -88,7 +88,7 @@ export class HollowdarkUserData extends Dexie { /** * Content cache — the compiled JSON chunks the client fetched from the * CDN. Independently versioned from user data; can be cleared without - * touching saves (ARCHITECTURE.md §3). + * touching saves. */ export class HollowdarkContentCache extends Dexie { content!: Table<CachedContentChunk, string> diff --git a/persistence/schema.ts b/persistence/schema.ts index 4d11edd..8d381d0 100644 --- a/persistence/schema.ts +++ b/persistence/schema.ts @@ -1,23 +1,17 @@ /** - * IndexedDB schema strings for each of the three Dexie databases. + * IndexedDB schema for the user-data database. The string values follow + * Dexie's index notation: * - * The schema is versioned deliberately — any change here requires a - * migration in persistence/migrations.ts (added later). Snapshot tests - * lock these strings so accidental drift shows up as a failing test - * rather than a silent mismatch between code and on-device data. - * - * Index syntax recap: * &field primary key (unique) * ++id auto-incrementing primary key * field plain index on a scalar * [a+b] compound index * *field multi-entry index on an array field * - * See ARCHITECTURE.md §24 for the user-data schema and §7 for the content - * cache; technical/04-persistence.md for the two-database separation - * (user data persists forever, content is replaceable per update). + * Frozen at module load so a runtime typo on the wrong key throws rather + * than silently mutating the schema object. Snapshot tests lock these + * strings; any change here requires a migration. */ - export const USER_DATA_SCHEMA_V1 = Object.freeze({ worlds: '&id, seed, currentPlayerCharacterId', people: @@ -35,16 +29,19 @@ export const USER_DATA_SCHEMA_V1 = Object.freeze({ settings: '&key' }) +/** IndexedDB schema for the content cache — replaceable per content update. */ export const CONTENT_CACHE_SCHEMA_V1 = Object.freeze({ content: '&chunkId, version, fetchedAt', manifest: '&id' }) +/** IndexedDB schema for the audio cache — blobs + a manifest row. */ export const AUDIO_CACHE_SCHEMA_V1 = Object.freeze({ audio: '&trackId, version, fetchedAt', manifest: '&id' }) +/** Current persistence schema version. Bump when any schema above changes. */ export const SCHEMA_VERSION = 1 as const export const USER_DATA_DB_NAME = 'HollowdarkUserData' as const diff --git a/rng/seeded.ts b/rng/seeded.ts index 52c4719..6d9f991 100644 --- a/rng/seeded.ts +++ b/rng/seeded.ts @@ -1,13 +1,12 @@ -import { deriveSeed, hashString } from './derive' +import { deriveSeed, hashString } from '@hollowdark/rng/derive' /** * Seeded PRNG. All gameplay randomness routes through this interface — - * Math.random is forbidden in gameplay code (see ARCHITECTURE.md §26 - * and eslint.config.js). + * Math.random is forbidden in gameplay code (see the ESLint rule). * * Guarantees: * - Same seed produces the same infinite sequence, bit-for-bit. - * - sub(label) produces a deterministic child stream, independent of + * - `sub(label)` produces a deterministic child stream, independent of * how the parent stream is consumed. * - Byte-level reproducibility across runs and machines. */ @@ -101,8 +100,6 @@ class SeededRNGImpl implements SeededRNG { cumulative += weight if (roll < cumulative) return value } - // Numerical safety: if we fall off the end due to floating-point drift, - // return the last item rather than throw. return items[items.length - 1]![0] } diff --git a/routes/+layout.svelte b/routes/+layout.svelte index d62f17d..35fb2d7 100644 --- a/routes/+layout.svelte +++ b/routes/+layout.svelte @@ -1,5 +1,4 @@ <script lang="ts"> - // Global CSS is loaded from static/css/app.css via <link> in app/app.html. let { children } = $props() </script> diff --git a/routes/+layout.ts b/routes/+layout.ts index 0b9e7c5..a032602 100644 --- a/routes/+layout.ts +++ b/routes/+layout.ts @@ -1,3 +1,2 @@ -// Pre-render everything. Static output matches adapter-static. export const prerender = true export const ssr = false diff --git a/routes/+page.svelte b/routes/+page.svelte index 00e0ed0..eeff5b2 100644 --- a/routes/+page.svelte +++ b/routes/+page.svelte @@ -1,5 +1,4 @@ <script lang="ts"> - // Main play screen. Placeholder until the flow stream is wired up in step 4+. </script> <main class="placeholder"> diff --git a/tests/determinism/rng.test.ts b/tests/determinism/rng.test.ts index 57a1e10..5d003b0 100644 --- a/tests/determinism/rng.test.ts +++ b/tests/determinism/rng.test.ts @@ -157,8 +157,6 @@ describe('createRNG — output shape', () => { ]) if (pick === 'rare') lowCount++ } - // Expected ~5, allow plenty of slack for variance; just confirm the - // distribution isn't inverted. expect(lowCount).toBeLessThan(50) }) @@ -212,15 +210,9 @@ describe('SeededRNG.sub — sub-RNG derivation', () => { }) describe('byte-level determinism snapshot', () => { - // Locks the PRNG implementation. Saved worlds depend on exact byte - // reproduction — if this test breaks, it means the PRNG changed, and - // every existing save relying on this seed will diverge. Treat failure - // as a migration concern, not a "just update the snapshot" fix. test('createRNG("hollowdark").next() × 5 matches canonical sequence', () => { const rng = createRNG('hollowdark') const first5 = [rng.next(), rng.next(), rng.next(), rng.next(), rng.next()] - // Values computed from the current mulberry32 + xmur3 implementation. - // Reproducible locally via: createRNG('hollowdark').next() × 5. expect(first5).toMatchInlineSnapshot(` [ 0.14088608953170478, diff --git a/tests/unit/time/calendar.test.ts b/tests/unit/time/calendar.test.ts index ee8d789..efbec97 100644 --- a/tests/unit/time/calendar.test.ts +++ b/tests/unit/time/calendar.test.ts @@ -72,10 +72,10 @@ describe('monthSeason', () => { }) test('specific month → season mappings', () => { - expect(monthSeason(1)).toBe('spring') // Thawing - expect(monthSeason(4)).toBe('summer') // Highsun - expect(monthSeason(7)).toBe('autumn') // Firstfall - expect(monthSeason(10)).toBe('winter') // Rainfall + expect(monthSeason(1)).toBe('spring') + expect(monthSeason(4)).toBe('summer') + expect(monthSeason(7)).toBe('autumn') + expect(monthSeason(10)).toBe('winter') expect(monthSeason(13)).toBe('festival') }) }) diff --git a/tests/unit/time/gameTime.test.ts b/tests/unit/time/gameTime.test.ts index ca6f4b1..9503e60 100644 --- a/tests/unit/time/gameTime.test.ts +++ b/tests/unit/time/gameTime.test.ts @@ -137,7 +137,6 @@ describe('addWeeks', () => { }) test('52 weeks lands in the festival, not at next year', () => { - // 52 × 7 = 364 days; Thawing 1 + 364 = Festival 5 (day 365 - 1) expect(addWeeks(makeGameTime(1111, 1, 1), 52)).toMatchObject({ year: 1111, month: 13, @@ -146,8 +145,6 @@ describe('addWeeks', () => { }) test('negative weeks moves backward', () => { - // Greening 1 (doy 31) minus 7 days = Thawing 24 (doy 24). - // Months are 30 days in this calendar, not 31. expect(addWeeks(makeGameTime(1111, 2, 1), -1)).toMatchObject({ year: 1111, month: 1, @@ -174,7 +171,6 @@ describe('addMonths', () => { }) test('overflow into next year wraps through the 13-month cycle', () => { - // Rimefrost 15 + 2 months → Festival → Thawing next year, day preserved (15) expect(addMonths(makeGameTime(1111, 12, 15), 2)).toMatchObject({ year: 1112, month: 1, diff --git a/tests/unit/utils/result.test.ts b/tests/unit/utils/result.test.ts index bdd4923..49cf86f 100644 --- a/tests/unit/utils/result.test.ts +++ b/tests/unit/utils/result.test.ts @@ -67,7 +67,6 @@ describe('type-narrowing', () => { test('isOk narrows to Ok<T>', () => { const r: Result<number, string> = ok(10) if (isOk(r)) { - // Type-level check — if isOk doesn't narrow, this line fails to compile. const n: number = r.value expect(n).toBe(10) } else { diff --git a/time/calendar.ts b/time/calendar.ts index ce61de4..e2f229f 100644 --- a/time/calendar.ts +++ b/time/calendar.ts @@ -1,8 +1,7 @@ /** - * The Hollowdark calendar: 12 months × 30 days + a 5-day year-end festival, - * 365 days per year, 7-day weeks. + * Number of days in a regular month. * - * Month order (per docs/01-world.md and style-bible/00-style-bible.md): + * Month order: * * spring 1 Thawing 2 Greening 3 Blossomtide * summer 4 Highsun 5 Amberhaze 6 Harvestmark @@ -10,20 +9,30 @@ * winter 10 Rainfall 11 Hollowdark 12 Rimefrost * festival 13 Year's End Festival (5 days) * - * The year begins with Thawing (spring) and closes with the festival, - * which sits between Rimefrost and the next year's Thawing. This matches - * the style bible's cold-half / warm-half grouping and the "year-end - * festival" phrasing in world lore. + * The year begins with Thawing and closes with the festival, which sits + * between Rimefrost and the next year's Thawing. */ - export const DAYS_PER_MONTH = 30 + +/** Twelve named months — all except the festival. */ export const REGULAR_MONTH_COUNT = 12 + +/** Days in the Year's End Festival — the thirteenth "month". */ export const FESTIVAL_DAYS = 5 + +/** Month index for the festival. */ export const FESTIVAL_MONTH = 13 -export const MONTHS_PER_YEAR = REGULAR_MONTH_COUNT + 1 // 12 regular + festival -export const DAYS_PER_YEAR = REGULAR_MONTH_COUNT * DAYS_PER_MONTH + FESTIVAL_DAYS // 365 + +/** Total month slots in the calendar cycle (12 regular + festival). */ +export const MONTHS_PER_YEAR = REGULAR_MONTH_COUNT + 1 + +/** Days in a year: 12 × 30 + 5 = 365. */ +export const DAYS_PER_YEAR = REGULAR_MONTH_COUNT * DAYS_PER_MONTH + FESTIVAL_DAYS + +/** Seven-day weeks. */ export const DAYS_PER_WEEK = 7 +/** Month names in calendar order. Index 0 is Thawing; index 12 is the festival. */ export const MONTH_NAMES = [ 'Thawing', 'Greening', @@ -40,23 +49,25 @@ export const MONTH_NAMES = [ "Year's End Festival" ] as const +/** The named-month type derived from `MONTH_NAMES`. */ export type MonthName = (typeof MONTH_NAMES)[number] +/** Four regular seasons plus a distinct `festival` tag for the year-end. */ export type Season = 'spring' | 'summer' | 'autumn' | 'winter' | 'festival' const SEASON_BY_MONTH: readonly Season[] = [ - 'spring', // Thawing - 'spring', // Greening - 'spring', // Blossomtide - 'summer', // Highsun - 'summer', // Amberhaze - 'summer', // Harvestmark - 'autumn', // Firstfall - 'autumn', // Stormturn - 'autumn', // Ashfall - 'winter', // Rainfall - 'winter', // Hollowdark - 'winter', // Rimefrost + 'spring', + 'spring', + 'spring', + 'summer', + 'summer', + 'summer', + 'autumn', + 'autumn', + 'autumn', + 'winter', + 'winter', + 'winter', 'festival' ] @@ -66,21 +77,33 @@ function validateMonth(monthIndex: number): void { } } +/** + * Return the named month for a 1-based month index. Throws on invalid input. + * @param monthIndex 1 (Thawing) through 13 (Year's End Festival). + */ export function monthName(monthIndex: number): MonthName { validateMonth(monthIndex) return MONTH_NAMES[monthIndex - 1] as MonthName } +/** + * Return the season label for a 1-based month index. The festival has its + * own tag ('festival') rather than reusing one of the four seasons. + */ export function monthSeason(monthIndex: number): Season { validateMonth(monthIndex) return SEASON_BY_MONTH[monthIndex - 1] as Season } +/** + * Days in the given month. 30 for regular months, 5 for the festival. + */ export function daysInMonth(monthIndex: number): number { validateMonth(monthIndex) return monthIndex === FESTIVAL_MONTH ? FESTIVAL_DAYS : DAYS_PER_MONTH } +/** True when the supplied month index is the festival slot. */ export function isFestival(monthIndex: number): boolean { return monthIndex === FESTIVAL_MONTH } diff --git a/time/gameTime.ts b/time/gameTime.ts index 2f2fed7..adebc4f 100644 --- a/time/gameTime.ts +++ b/time/gameTime.ts @@ -8,16 +8,15 @@ import { REGULAR_MONTH_COUNT, daysInMonth, monthName -} from './calendar' +} from '@hollowdark/time/calendar' /** * A position in game time. Immutable — all arithmetic returns a new value. * - * year integer (negative allowed for pre-1111 historical events) + * year integer (negative allowed for pre-epoch historical events) * month 1..12 for regular months, 13 for year-end festival * day 1..30 for regular months, 1..5 for festival * tickOfDay 0 outside crisis mode; crisis mode subdivides the day - * (docs/22-crisis-mode.md) */ export interface GameTime { readonly year: number @@ -61,23 +60,21 @@ function absoluteDays(time: GameTime): number { } function fromAbsoluteDays(abs: number, tickOfDay: number): GameTime { - // Guard against non-integer arithmetic drift — time is whole days only, - // tickOfDay handles sub-day resolution in crisis mode. if (!Number.isFinite(abs)) { throw new Error(`Non-finite absolute day count: ${abs}`) } const year = Math.floor(abs / DAYS_PER_YEAR) - const rem = abs - year * DAYS_PER_YEAR // 0..364 - const doy = rem + 1 // 1..365 - const festivalStart = REGULAR_MONTH_COUNT * DAYS_PER_MONTH + 1 // 361 + const rem = abs - year * DAYS_PER_YEAR + const doy = rem + 1 + const festivalStart = REGULAR_MONTH_COUNT * DAYS_PER_MONTH + 1 let month: number let day: number if (doy >= festivalStart) { month = FESTIVAL_MONTH - day = doy - festivalStart + 1 // 1..5 + day = doy - festivalStart + 1 } else { - month = Math.floor((doy - 1) / DAYS_PER_MONTH) + 1 // 1..12 - day = ((doy - 1) % DAYS_PER_MONTH) + 1 // 1..30 + month = Math.floor((doy - 1) / DAYS_PER_MONTH) + 1 + day = ((doy - 1) % DAYS_PER_MONTH) + 1 } return { year, month, day, tickOfDay } } @@ -105,7 +102,6 @@ export function addMonths(time: GameTime, months: number): GameTime { if (!Number.isInteger(months)) { throw new Error(`addMonths requires an integer (got ${months})`) } - // Zero-based cycle arithmetic: months are 1..13, so we work in 0..12. const totalCycles = (time.month - 1) + months const yearDelta = Math.floor(totalCycles / MONTHS_PER_YEAR) const monthIndex = ((totalCycles % MONTHS_PER_YEAR) + MONTHS_PER_YEAR) % MONTHS_PER_YEAR @@ -171,7 +167,6 @@ export function toAbsoluteDays(time: GameTime): number { return absoluteDays(time) } -// Re-exports for convenience at the 'time' import. export { DAYS_PER_MONTH, DAYS_PER_WEEK, diff --git a/time/granularity.ts b/time/granularity.ts index 0643c47..1acb122 100644 --- a/time/granularity.ts +++ b/time/granularity.ts @@ -1,12 +1,7 @@ /** - * Tick granularity by life stage. - * - * One tick represents a different span of time depending on the character's - * age — infancy advances in years because there isn't weekly texture worth - * resolving, adulthood in weeks because that's the rhythm the design lives - * at. See docs/05-time-system.md and ARCHITECTURE.md §5. + * The eight life stages a character moves through. Used to pick how much + * wall-clock time one simulation tick represents at a given age. */ - export type LifeStage = | 'infancy' | 'early_childhood' @@ -17,8 +12,15 @@ export type LifeStage = | 'late_adult' | 'elderly' +/** How much game time one tick advances. */ export type TickUnit = 'year' | 'season' | 'month' | 'week' +/** + * Tick granularity per life stage. Infancy advances in years because + * there isn't weekly texture worth resolving; adulthood in weeks because + * that's the rhythm the design lives at; elderly in months as the pace + * slows again. + */ export const TICK_UNIT_BY_LIFE_STAGE: Readonly<Record<LifeStage, TickUnit>> = { infancy: 'year', early_childhood: 'season', @@ -30,6 +32,9 @@ export const TICK_UNIT_BY_LIFE_STAGE: Readonly<Record<LifeStage, TickUnit>> = { elderly: 'month' } +/** + * Bucket an age in whole years into its life stage. Throws on negative age. + */ export function lifeStageForAge(ageYears: number): LifeStage { if (ageYears < 0) throw new Error(`Invalid age: ${ageYears}`) if (ageYears < 3) return 'infancy' @@ -42,6 +47,7 @@ export function lifeStageForAge(ageYears: number): LifeStage { return 'elderly' } +/** Shortcut: map an age directly to its tick unit. */ export function tickUnitForAge(ageYears: number): TickUnit { return TICK_UNIT_BY_LIFE_STAGE[lifeStageForAge(ageYears)] } diff --git a/time/speed.ts b/time/speed.ts index 9a9bb11..d5cba2e 100644 --- a/time/speed.ts +++ b/time/speed.ts @@ -1,11 +1,11 @@ /** - * Player-controlled simulation speed. Only three states ever exist - * (docs/05-time-system.md): time is stopped, running at reading pace, - * or running fast with compressed flow. - * - * Scenes auto-set the effective speed to 'paused'; the intended speed is - * preserved so the simulation returns to it when the scene resolves. + * Player-controlled simulation speed. Only three states ever exist: time + * is stopped, running at reading pace, or running fast with compressed + * flow. Scenes auto-set the effective speed to `paused`; the intended + * speed is preserved so the simulation returns to it when the scene + * resolves. */ export type Speed = 'paused' | 'play' | 'fast' +/** The three speeds, in canonical order. */ export const SPEEDS: readonly Speed[] = ['paused', 'play', 'fast'] diff --git a/utils/result/constructors.ts b/utils/result/constructors.ts index b0ed958..6fec0f4 100644 --- a/utils/result/constructors.ts +++ b/utils/result/constructors.ts @@ -1,4 +1,4 @@ -import type { Err, Ok } from './types' +import type { Err, Ok } from '@hollowdark/utils/result/types' export function ok<T>(value: T): Ok<T> { return { ok: true, value } diff --git a/utils/result/map.ts b/utils/result/map.ts index 9cf44a1..6d8697e 100644 --- a/utils/result/map.ts +++ b/utils/result/map.ts @@ -1,5 +1,5 @@ -import { err, ok } from './constructors' -import type { Result } from './types' +import { err, ok } from '@hollowdark/utils/result/constructors' +import type { Result } from '@hollowdark/utils/result/types' /** Map the value of an ok result; pass errors through unchanged. */ export function mapResult<T, U, E>(r: Result<T, E>, f: (value: T) => U): Result<U, E> { diff --git a/utils/result/predicates.ts b/utils/result/predicates.ts index 315eb0d..16e37af 100644 --- a/utils/result/predicates.ts +++ b/utils/result/predicates.ts @@ -1,4 +1,4 @@ -import type { Err, Ok, Result } from './types' +import type { Err, Ok, Result } from '@hollowdark/utils/result/types' export function isOk<T, E>(r: Result<T, E>): r is Ok<T> { return r.ok diff --git a/utils/result/types.ts b/utils/result/types.ts index ee95c08..e22856f 100644 --- a/utils/result/types.ts +++ b/utils/result/types.ts @@ -8,7 +8,7 @@ export type Err<E> = { readonly ok: false; readonly error: E } * Result<T, E> — a recoverable-error return type for functions that can * fail without throwing. Used at system boundaries (save/load, content * validation, manifest fetch) where the caller needs to decide whether a - * failure is fatal. Internal pure logic uses plain returns and throws - * Error for programmer errors (rules/01-code-style.md). + * failure is fatal. Internal pure logic still throws `Error` for + * programmer errors. */ export type Result<T, E = Error> = Ok<T> | Err<E> diff --git a/utils/result/unwrap.ts b/utils/result/unwrap.ts index 84e658e..8f980dd 100644 --- a/utils/result/unwrap.ts +++ b/utils/result/unwrap.ts @@ -1,4 +1,4 @@ -import type { Result } from './types' +import type { Result } from '@hollowdark/utils/result/types' /** * Extract the value from an ok result; throw on error. Reserve for tests |