diff --git a/architecture.md b/architecture.md new file mode 100644 index 0000000..30c9700 --- /dev/null +++ b/architecture.md @@ -0,0 +1,28 @@ +--- +id: architecture +type: architecture-design +status: draft +title: Living Systems Lab architecture +parent: living-systems-lab +--- + +## Drivers + +The site is a static browser lab: two simulations a visitor can open without signing in, in the language chosen in `i18n`. There is no application server and no shared session. + +## Decisions + +- Each page is a lazy route. The empty path opens the meadow. Feature pages do not import one another. +- The meadow is a walled habitat. Life wraps by default, and the visitor can turn wrap off. That split is deliberate: wrap-around is a Life lesson, not a rule both labs share. See `meadow` and `game-of-life`. +- A meadow story opens from a fixed seed, so the named openings match every time. Once it is running, each day draws from an unseeded random source, so the same opening is not replayable. That divergence is intentional. +- A tick's rules stay in that lab's engine. The page may schedule time, paint, and stop playback. It does not reimplement the neighbor rule. + +## Invariants + +- `meadow` must not import `game-of-life` or `how-it-works`, and those pages must not import `meadow`. +- Visitor strings go through `i18n`. English is the key set. The legal page is the exception (`app-shell`). +- The shell does not own a grid. Each lab owns its own world for the life of the page. + +## Limitations + +- Reloading the page drops the meadow and the colony. The language choice is the only preference kept. diff --git a/goal-and-requirements.md b/goal-and-requirements.md new file mode 100644 index 0000000..592e5ec --- /dev/null +++ b/goal-and-requirements.md @@ -0,0 +1,37 @@ +--- +id: living-systems-lab +type: goal-and-requirements +status: draft +title: Living Systems Lab +--- + +## Goal + +Living Systems Lab is a public teaching site. A visitor explores two living grids in English or German: a food-chain meadow, and Conway's Game of Life. The Angular app is that site, not a generic starter template. + +## Problem + +Unconfirmed: a first encounter with these systems is usually a static explanation or a research toy. The lab exists so a visitor can change a cell and watch the local rule answer, with no account and no install. + +## Audience + +Visitors to the public site. They can read the lab in English or German. They do not sign in. + +## Capabilities + +- Meadow Makers: paint plants, plant eaters, predators, or erase; run, step, or reset; open a seeded story (balanced, green meadow, or predator boom); change speed and species behavior; read population totals and one animal's energy; see the food-chain clue. Playback stops when no animals remain. +- Conway's Way of Life: germinate, step, replant, or clear; change speed; toggle wrap-around; plant with brushes; start from a Methuselah seed; read living, sprout, perennial, and withered counts. Playback stops when nothing is alive. The rule is B3/S23, and there is no score. +- A page that explains those Conway rules and what the Life page shows. +- A language switch that survives reload. +- One legal page, linked from the footer, that states the operator and the privacy notice together. It is not a second simulation and not two routes. + +## Non-goals + +- Accounts, cookies, forms, and any saved visitor profile. Remembering the language choice is not a profile. + +Anything not listed here is open, not forbidden. + +## Principles + +- Teaching happens on a grid the visitor can edit, not behind an account. +- Meadow rules and Life rules stay separate. They do not share an edge rule or a tick. diff --git a/src/app/SPEC.md b/src/app/SPEC.md new file mode 100644 index 0000000..d5c3acc --- /dev/null +++ b/src/app/SPEC.md @@ -0,0 +1,20 @@ +--- +id: app-shell +type: module-design +status: draft +title: App shell +parent: architecture +depends-on: [i18n] +--- + +## Responsibility + +Chrome and routing for the lab: the brand, links to the meadow, Life, and the Conway explanation, the language switch, and the legal footer. The empty path opens the meadow. Pages load on navigation. + +Shared helpers live here because both labs need them and neither owns them: the speed names, a cell position, and keyboard movement of grid focus. They are not a third simulation. Arrow keys move focus and stop at the edge. Focus does not wrap, including on the Life grid, whose wrap setting applies only to the neighbor rule. + +## Boundary + +May use the router and `i18n`. Must not import a feature engine, or a feature component except through the route loader. Must not reach into another feature to read or write its grid. + +The legal page is one route, not a module boundary, and it does not own simulation behavior. It states the operator and the privacy notice. Specs do not copy the operator's name or address. German on that page is the binding text; English is a courtesy translation. A language switch swaps the whole notice. Those paragraphs are not `i18n` keys, which is why this page is the exception to the string invariant in `architecture`. Hosting and analytics sentences there are the notice's own claims. Unconfirmed: this repository does not embed an analytics client, so those sentences are not an app behavior. diff --git a/src/app/features/game-of-life/SPEC.md b/src/app/features/game-of-life/SPEC.md new file mode 100644 index 0000000..979604a --- /dev/null +++ b/src/app/features/game-of-life/SPEC.md @@ -0,0 +1,26 @@ +--- +id: game-of-life +type: module-design +status: draft +title: Conway's Way of Life +parent: app-shell +depends-on: [i18n] +--- + +## Responsibility + +Conway's Game of Life as a garden the visitor can seed, brush, and run. The rule is B3/S23. There is no score and no win state. + +## Boundary + +May depend on `i18n` and the shell helpers for speed names, cell position, and grid focus. Must not import `meadow` or `how-it-works`. Birth, survival, and death stay in the Life engine. `how-it-works` states this rule for visitors and must not be imported to enforce it. + +## Rules + +Each generation is one pass over the current grid. A dead cell with exactly 3 live neighbors is born. A live cell with 2 or 3 live neighbors survives and ages by one. Any other live cell dies. Age is display only: sprout at 1, growing flora at 2–5, perennial at 6 and above. Age does not change the rule. The withered count is deaths in the last generation, not an age stage. + +Wrap-around is on by default, so opposite edges meet. The visitor can turn it off; cells past the edge then count as dead. Toggling wrap does not reset the generation. This topology is not shared with `meadow`. + +Playback stops when no cell is alive, and will not start from an empty field. + +Seeds (acorn, R-pentomino, diehard, rabbits, glider armada) and brushes (single cell, glider, blinker, acorn, eraser) only plant or erase. Replant restores the active seed. Clear empties the field and keeps the current wrap setting. diff --git a/src/app/features/how-it-works/SPEC.md b/src/app/features/how-it-works/SPEC.md new file mode 100644 index 0000000..c2d3f08 --- /dev/null +++ b/src/app/features/how-it-works/SPEC.md @@ -0,0 +1,21 @@ +--- +id: how-it-works +type: module-design +status: draft +title: How Conway's Game of Life works +parent: app-shell +depends-on: [i18n] +references: [game-of-life] +--- + +## Responsibility + +Explain Conway's Game of Life in the visitor's language: the idea, what the Life page shows, and the B3/S23 pass, including wrap-around. Link the visitor back into the simulation. + +## Boundary + +May depend on `i18n` only. Must not import the Life engine or turn pattern tables into a second implementation of the rule. + +The prose must stay true to `game-of-life`: Moore neighborhood of 8, birth on 3, survival on 2 or 3, death otherwise, wrap on by default, and dead-beyond-the-edge when wrap is off. Age stages are display, not rule inputs. + +This page explains Conway only. It does not own meadow rules; those stay in `meadow`. diff --git a/src/app/features/meadow/SPEC.md b/src/app/features/meadow/SPEC.md new file mode 100644 index 0000000..36721bf --- /dev/null +++ b/src/app/features/meadow/SPEC.md @@ -0,0 +1,37 @@ +--- +id: meadow +type: module-design +status: draft +title: Meadow Makers +parent: app-shell +depends-on: [i18n] +--- + +## Responsibility + +The food-chain lab. A visitor paints and runs a meadow of plants, plant eaters, and predators, and watches each group affect the next. + +## Boundary + +May depend on `i18n` and the shell helpers for speed names and grid focus. Must not import `game-of-life` or `how-it-works`. The engine has no UI dependency. The page may schedule playback and paint cells; it must not reimplement a day. + +The grid is walled. Animals do not wrap. That is not the Life edge rule (`architecture`). + +## Rules + +A day proceeds in this order: + +1. An empty tile grows a plant when enough neighboring plants exist and the growth roll succeeds. A plant hidden under an animal counts as a plant neighbor. +2. An animal that reaches its max age dies and leaves no move. +3. A hungry animal, one whose energy is below its hunger line, may eat an adjacent prey: plants for plant eaters, plant eaters for predators. A full animal does not hunt. It wanders onto an empty or plant tile and spends energy. Satiation is the lesson, and the hunger sliders are part of it. +4. Predators resolve before plant eaters. An eaten plant eater does not finish its move. Predators win that race. +5. Walking onto a plant does not eat it. The plant stays hidden and regrows when the tile is empty again. Only a hungry plant eater consumes a plant. A predator that eats a plant eater keeps that hidden plant, so the plant is not lost with the prey. +6. An animal with enough energy may reproduce into a different empty neighbor, paying an energy cost. An animal whose energy would fall to zero or below is not placed. + +Playback stops when no animals remain, and will not start on a meadow with none. + +Balanced, Green meadow, and Predator boom open from fixed seeds, so each story starts the same way. Running days are not seeded. The same opening is meant to diverge. + +Behavior sliders change growth, reproduction chance, food energy, max age, and hunger for the next day. They do not rewrite the current grid. + +Inspection shows one animal's energy, position, and whether a plant is hidden under it. Hover previews. A pinned card stays until dismissed, or until that cell no longer holds that animal. diff --git a/src/app/shared/i18n/SPEC.md b/src/app/shared/i18n/SPEC.md new file mode 100644 index 0000000..a831f29 --- /dev/null +++ b/src/app/shared/i18n/SPEC.md @@ -0,0 +1,21 @@ +--- +id: i18n +type: submodule-design +status: draft +title: Visitor language +parent: app-shell +--- + +## Responsibility + +English and German visitor strings, and the remembered language. The document language follows the choice. + +## Boundary + +English is the key set. German must define every English key. A missing German key is a broken contract. + +The only stored preference is the language entry. This module must not store a grid, a seed, or any other visitor data, and it must not set a cookie. + +It does not own the legal notice. That page reads the language signal and is not a dictionary (`app-shell`). + +On first visit, use the saved choice if it is English or German. Otherwise use German when the browser language starts with `de`, and English otherwise. If storage is unavailable, skip the save and still switch the document language.