feat(editor): browse samples in a categorized modal gallery

Replace the cramped Samples dropdown with a modal that lays the gallery
out as a card grid, sectioned by tier, so the growing set stays scannable
and the learning order is visible at once.

docs/adr/0004-rate-rules-not-formulas.md

@@ -22,20 +22,33 @@ typed-in formula.** Each instantaneous element picks one rule and a plain number
 or two — never an expression:
 
 | Rule             | Value                                  | Reads (via Information Links)                | Emergent behaviour         |
-| ---------------- | --------------------------- | ----------------------------------------- | -------------------------- |
+| ---------------- | -------------------------------------- | -------------------------------------------- | -------------------------- |
 | **Constant**     | a fixed number                         | nothing                                      | linear Stock change        |
 | **Proportional** | `factor × (its `+` inputs)`            | the `+`-polarity inputs                      | exponential growth / decay |
 | **Gap**          | `factor × (level − target)`            | the `+` input is _level_, `−` is _target_    | goal-seeking / asymptotic  |
+| **Overflow**     | `max(0, factor × (level − threshold))` | the `+` input is _level_, `−` is _threshold_ | a spillway / hard ceiling  |
 
 The famous curves are _compositions_ of these over the structure — a logistic
 S-curve is Proportional growth meeting a Gap-driven ceiling (limits-to-growth);
 goal-seeking decay is a lone Gap (coffee cooling). The user sets up a local rule;
 the global shape **emerges**. That emergence _is_ the lesson.
 
+**Overflow is the one _declared_ limit.** Constant/Proportional/Gap are smooth and
+their ceilings _emerge_ (the S-curve is two of them meeting); Overflow instead is a
+threshold — `max(0, …)` that stays shut until a level crosses it, then spills the
+excess down an outflow (a bathtub brimming onto the floor). It earns a rule of its
+own because Gap _cannot_ stand in: Gap is signed and bidirectional (coffee re-warms
+if it drops below the room), so a Gap outflow runs _backwards_ below its target, and
+that clamp can't be applied to Gap globally without breaking the goal-seekers. So
+Overflow is a deliberate exception to "the shape emerges" — a hard ceiling you
+_declare_, for the real limit that is a wall, not a slope (and the rate-side sibling
+of the non-negative-Stock floor the integrator already enforces).
+
 **Polarity does double duty.** The `+`/`−` already captured for loop
 classification (ADR-0001) also selects each operand's role: Proportional reads
 its `+` inputs; Gap reads its `+` input as the level and its `−` input as the
-target. One gesture, two payoffs — no new per-link data.
+target, and Overflow the same with its `−` input as the threshold. One gesture,
+two payoffs — no new per-link data.
 
 ## Considered Options
 
@@ -70,5 +83,7 @@ target. One gesture, two payoffs — no new per-link data.
 - The vocabulary starts deliberately small (Constant / Proportional / Gap —
   enough for linear, exponential, and goal-seeking, and for the coffee and
   savings samples). Growing it is additive: a new `kind` in the union plus a case
-  in the evaluator. Multi-input products (e.g. `Population × fertility`) are a
-  later increment, not a phase-2 blocker.
+  in the evaluator — as **Overflow** later bore out (one union member, one
+  evaluator case, plus matching touch-ups to the rule validator and the
+  inspector). Multi-input products (e.g. `Population × fertility`) are a later
+  increment, not a phase-2 blocker.

src/components/Editor.vue

@@ -24,12 +24,12 @@ import {
   VueFlow,
   type XYPosition,
 } from "@vue-flow/core"
-import { computed, onBeforeUnmount, onMounted, ref, useTemplateRef } from "vue"
+import { computed, onBeforeUnmount, onMounted, ref, useTemplateRef, watch } from "vue"
 import { useAutosave } from "@/composables/useAutosave"
 import { usePlayback } from "@/composables/usePlayback"
 import { parseModel, serializeModel } from "@/model/io"
 import { project } from "@/model/projection"
-import { type Sample, SAMPLES } from "@/model/samples"
+import type { Sample } from "@/model/samples"
 import { canConnect } from "@/model/validation"
 import { useModelStore } from "@/store/model"
 import { NODE_DND_MIME, type PlaceableKind } from "./palette-dnd"
@@ -38,6 +38,7 @@ import Inspector from "./Inspector.vue"
 import LoopOverlay from "./LoopOverlay.vue"
 import Palette from "./Palette.vue"
 import ResultsPanel from "./ResultsPanel.vue"
+import SampleBrowser from "./SampleBrowser.vue"
 import InfoLinkEdge from "./edges/InfoLinkEdge.vue"
 import PipeEdge from "./edges/PipeEdge.vue"
 import CloudNode from "./nodes/CloudNode.vue"
@@ -55,6 +56,9 @@ const edges = computed(() => graph.value.edges)
 // the Model and recomputes reactively while open.
 const showResults = ref(false)
 
+// The sample-browser modal (opened from the header "Samples" button).
+const browserOpen = ref(false)
+
 // The playback clock that advances the playhead while a run is playing (mounted
 // once here; the simulation store holds the state it drives).
 usePlayback()
@@ -74,6 +78,7 @@ const {
   getSelectedEdges,
   viewport,
   vueFlowRef,
+  dimensions,
   fitView,
 } = useVueFlow("meadows")
 
@@ -89,6 +94,26 @@ onNodesInitialized(() => {
   fitView({ padding: 0.2 })
 })
 
+// Docking the results panel (Simulate) shrinks the canvas; closing it gives the
+// space back. Re-fit either way so the whole diagram stays framed in whatever
+// height remains. Vue Flow re-measures the pane a frame after the panel
+// mounts/unmounts and republishes the size via `dimensions`; fitting on *that*
+// signal (not straight after the toggle) frames against the settled size, so the
+// diagram never lands jammed against the new edge. The flag scopes the fit to
+// panel toggles, leaving ordinary window resizes to Vue Flow's own handling.
+let fitOnResize = false
+watch(showResults, () => {
+  fitOnResize = true
+})
+watch(
+  () => [dimensions.value.width, dimensions.value.height],
+  () => {
+    if (!fitOnResize) return
+    fitOnResize = false
+    fitView({ padding: 0.2 })
+  },
+)
+
 // Restore the last document on mount and persist every change (F7). Arm the same
 // post-measure fit a load uses; fitting synchronously in onRestore would frame
 // against unmeasured 0×0 nodes, landing the restored model jammed top-left.
@@ -249,12 +274,12 @@ function onDragOver(event: DragEvent): void {
  */
 function loadSample(sample: Sample): void {
   if (store.nodeCount > 0 && !window.confirm(`Replace the current model with “${sample.title}”?`)) {
+    // Cancelled: leave the model untouched and the browser open to pick again.
     return
   }
   fitAfterInit = true
   store.setModel(sample.build())
-  // Close the DaisyUI dropdown (it stays open while the trigger keeps focus).
-  ;(document.activeElement as HTMLElement | null)?.blur()
+  browserOpen.value = false
 }
 
 const fileInput = useTemplateRef<HTMLInputElement>("fileInput")
@@ -376,20 +401,7 @@ onBeforeUnmount(() => {
         {{ store.nodeCount }} {{ store.nodeCount === 1 ? "element" : "elements" }}
       </span>
       <div class="ml-auto flex items-center gap-1">
-        <div class="dropdown dropdown-end">
-          <button tabindex="0" class="btn btn-ghost btn-sm">Samples</button>
-          <ul
-            tabindex="0"
-            class="dropdown-content menu z-40 mt-1 max-h-80 w-72 flex-nowrap gap-1 overflow-y-auto rounded-box border border-base-300 bg-base-100 p-2 shadow-lg"
-          >
-            <li v-for="sample in SAMPLES" :key="sample.title">
-              <button class="flex flex-col items-start gap-0.5" @click="loadSample(sample)">
-                <span class="font-medium">{{ sample.title }}</span>
-                <span class="text-xs text-base-content/60">{{ sample.blurb }}</span>
-              </button>
-            </li>
-          </ul>
-        </div>
+        <button class="btn btn-ghost btn-sm" @click="browserOpen = true">Samples</button>
         <button
           class="btn btn-primary btn-sm"
           :class="{ 'btn-active': showResults }"
@@ -460,7 +472,6 @@ onBeforeUnmount(() => {
       <LoopOverlay />
       <GlossPanel />
       <Inspector />
-      <ResultsPanel v-if="showResults" @close="showResults = false" />
 
       <!-- Self-dismissing teaching hint, e.g. when a Flow is dragged back onto its
            own Stock to "close the loop". Click to dismiss early; z-30 keeps it above
@@ -479,5 +490,12 @@ onBeforeUnmount(() => {
         </div>
       </div>
     </div>
+
+    <!-- Docked beneath the canvas (not floating over it): opening Simulate shrinks
+         the canvas to the space above, where the diagram re-fits (see the
+         `dimensions` watcher in <script>). -->
+    <ResultsPanel v-if="showResults" @close="showResults = false" />
+
+    <SampleBrowser v-model:open="browserOpen" @select="loadSample" />
   </div>
 </template>

src/components/Inspector.vue

@@ -14,20 +14,25 @@
 import { useVueFlow } from "@vue-flow/core"
 import { computed } from "vue"
 import type { EdgeData } from "@/model/projection"
-import type { ConverterNode, FlowNode, Rule, StockNode } from "@/model/types"
+import type { ConverterNode, FlowNode, InformationLink, Rule, StockNode } from "@/model/types"
 import { useModelStore } from "@/store/model"
 
 const store = useModelStore()
 const { getSelectedNodes, getSelectedEdges } = useVueFlow("meadows")
 
-/** The single selected element's id — a node directly, or a Flow via its pipe edge. */
+/**
+ * The single selected element's id — a node directly, a Flow via its pipe edge,
+ * or an Information Link via its info edge (the edge id *is* the link id).
+ */
 const selectedId = computed<string | null>(() => {
   const nodes = getSelectedNodes.value
   const edges = getSelectedEdges.value
   if (nodes.length === 1 && edges.length === 0) return nodes[0].id
   if (edges.length === 1 && nodes.length === 0) {
     const edge = edges[0]
-    if ((edge.data as EdgeData | undefined)?.kind === "pipe") return edge.id.split("::")[0]
+    const kind = (edge.data as EdgeData | undefined)?.kind
+    if (kind === "pipe") return edge.id.split("::")[0]
+    if (kind === "info") return edge.id
   }
   return null
 })
@@ -41,8 +46,21 @@ const element = computed<StockNode | FlowNode | ConverterNode | null>(() => {
   return null
 })
 
+/** The live Information Link behind the selection, when a link (not a node) is selected. */
+const link = computed<InformationLink | null>(() => {
+  const id = selectedId.value
+  if (!id) return null
+  return store.model.infoLinks.find((l) => l.id === id) ?? null
+})
+
 const KIND_LABEL = { stock: "Stock", flow: "Flow", converter: "Converter" } as const
 
+/** A link's endpoints are always named nodes — it never touches a Cloud (validation.ts). */
+function nodeName(id: string): string {
+  const node = store.model.nodes.find((n) => n.id === id)
+  return node && "name" in node ? node.name : ""
+}
+
 /** Every rule carries exactly one number (a value or a factor); read it uniformly. */
 function ruleNumber(rule?: Rule): number {
   if (!rule) return 0
@@ -68,6 +86,13 @@ function onUnit(event: Event): void {
   store.setUnit(el.id, (event.target as HTMLInputElement).value)
 }
 
+/** Write the description for whichever element (node or link) is selected. */
+function onDescription(event: Event): void {
+  const id = element.value?.id ?? link.value?.id
+  if (!id) return
+  store.setDescription(id, (event.target as HTMLTextAreaElement).value)
+}
+
 function onKind(event: Event): void {
   const el = element.value
   if (el?.kind !== "flow" && el?.kind !== "converter") return
@@ -90,14 +115,18 @@ const RULE_HINT: Record<Rule["kind"], string> = {
   constant: "A fixed number — no inputs.",
   proportional: "rate = factor × its “+” inputs.",
   gap: "rate = factor × (level − target): the “+” input is the level, the “−” the target.",
+  overflow:
+    "rate = max(0, factor × (level − threshold)): spills only once the “+” level passes the “−” threshold.",
 }
 </script>
 
 <template>
   <div
-    v-if="element"
+    v-if="element || link"
     class="absolute top-3 right-3 z-20 w-60 rounded-box border border-base-300 bg-base-100/95 p-3 shadow-md backdrop-blur"
   >
+    <!-- A named node: Stock (value + unit) or Flow/Converter (rule). -->
+    <template v-if="element">
       <div class="flex items-baseline gap-2">
         <span class="text-sm font-semibold">{{ element.name }}</span>
         <span class="text-xs text-base-content/50">{{ KIND_LABEL[element.kind] }}</span>
@@ -140,6 +169,7 @@ const RULE_HINT: Record<Rule["kind"], string> = {
             <option value="constant">Constant</option>
             <option value="proportional">Proportional</option>
             <option value="gap">Gap</option>
+            <option value="overflow">Overflow</option>
           </select>
         </label>
 
@@ -160,5 +190,29 @@ const RULE_HINT: Record<Rule["kind"], string> = {
           {{ RULE_HINT[element.rule.kind] }}
         </p>
       </template>
+    </template>
+
+    <!-- An Information Link: its endpoints and polarity, then its description. -->
+    <template v-else-if="link">
+      <div class="flex items-baseline gap-2">
+        <span class="text-sm font-semibold">Information Link</span>
+        <span class="text-xs text-base-content/50">{{ link.polarity === "+" ? "+" : "−" }}</span>
+      </div>
+      <p class="mt-1 text-xs text-base-content/60">
+        {{ nodeName(link.source) }} → {{ nodeName(link.target) }}
+      </p>
+    </template>
+
+    <!-- Shared across nodes and links: the "why this element is here" note (G4). -->
+    <label class="mt-2 block">
+      <span class="text-xs text-base-content/60">Description</span>
+      <textarea
+        rows="6"
+        class="textarea textarea-bordered textarea-sm mt-1 w-full leading-snug"
+        :value="(element ?? link)?.description ?? ''"
+        placeholder="Why this element is here…"
+        @change="onDescription"
+      />
+    </label>
   </div>
 </template>

src/components/ResultsPanel.vue

@@ -59,9 +59,7 @@ const chart = computed(() => {
 </script>
 
 <template>
-  <div
-    class="absolute inset-x-3 bottom-3 z-30 rounded-box border border-base-300 bg-base-100/95 p-3 shadow-lg backdrop-blur"
-  >
+  <div class="shrink-0 border-t border-base-300 bg-base-100 p-3">
     <div class="flex items-center gap-2">
       <span class="text-sm font-semibold">Behaviour over time</span>
       <span class="truncate text-xs text-base-content/50">{{ store.model.name }}</span>

src/components/SampleBrowser.vue

@@ -0,0 +1,85 @@
+<script setup lang="ts">
+/**
+ * Sample browser — a modal gallery of the curated example models, laid out as a
+ * card grid sectioned by pedagogical tier (Primer → … → Mechanics & capstone).
+ * As the gallery grows this beats the old narrow dropdown: the whole set stays
+ * scannable in one scroll and the tiers show how the samples relate.
+ *
+ * Presentational only — it never touches the Model store. Picking a card emits
+ * `select`; the Editor owns the confirm/replace/fit logic (one place for it).
+ * Built on the native <dialog> so Esc, the backdrop click and focus-trapping come
+ * for free; `open` drives showModal()/close() and the native close event keeps the
+ * parent's state in sync.
+ */
+import { computed, useTemplateRef, watch } from "vue"
+import { type Sample, SAMPLE_CATEGORIES, SAMPLES } from "@/model/samples"
+
+const props = defineProps<{ open: boolean }>()
+const emit = defineEmits<{ "update:open": [boolean]; select: [Sample] }>()
+
+const dialog = useTemplateRef<HTMLDialogElement>("dialog")
+
+// Mirror the `open` prop onto the native dialog (showModal gives us the focus trap
+// and inert backdrop a plain div can't).
+watch(
+  () => props.open,
+  (open) => {
+    const el = dialog.value
+    if (!el) return
+    if (open && !el.open) el.showModal()
+    else if (!open && el.open) el.close()
+  },
+)
+
+// Fired by Esc, the backdrop form, the ✕, or our own close() — fold them all into
+// one update:open so the parent's state can't drift from the dialog's.
+function onClose(): void {
+  if (props.open) emit("update:open", false)
+}
+
+// The categories in display order, each with its samples (SAMPLES is already in
+// pedagogical order, so first-appearance order is preserved). Empty tiers drop out.
+const sections = computed(() =>
+  SAMPLE_CATEGORIES.map((category) => ({
+    category,
+    samples: SAMPLES.filter((sample) => sample.category === category),
+  })).filter((section) => section.samples.length > 0),
+)
+</script>
+
+<template>
+  <dialog ref="dialog" class="modal" @close="onClose">
+    <div class="modal-box w-11/12 max-w-3xl">
+      <div class="mb-4 flex items-center gap-2">
+        <h3 class="text-base font-semibold">Browse samples</h3>
+        <span class="text-xs text-base-content/50">{{ SAMPLES.length }} models</span>
+        <form method="dialog" class="ml-auto">
+          <button class="btn btn-circle btn-ghost btn-sm" aria-label="Close">✕</button>
+        </form>
+      </div>
+
+      <section v-for="section in sections" :key="section.category" class="mb-5 last:mb-0">
+        <h4 class="mb-2 text-xs font-semibold tracking-wide text-base-content/50 uppercase">
+          {{ section.category }}
+        </h4>
+        <div class="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
+          <button
+            v-for="sample in section.samples"
+            :key="sample.title"
+            type="button"
+            class="flex flex-col gap-1 rounded-box border border-base-300 bg-base-100 p-3 text-left transition hover:border-primary hover:shadow-md"
+            @click="emit('select', sample)"
+          >
+            <span class="font-medium">{{ sample.title }}</span>
+            <span class="text-xs text-base-content/60">{{ sample.blurb }}</span>
+          </button>
+        </div>
+      </section>
+    </div>
+
+    <!-- Click outside the box to dismiss (submits the dialog → fires @close). -->
+    <form method="dialog" class="modal-backdrop">
+      <button aria-label="Close">close</button>
+    </form>
+  </dialog>
+</template>

src/components/SimChart.vue

@@ -76,8 +76,54 @@ function themeColor(name: string, fallback: string): string {
   return value || fallback
 }
 
+/**
+ * Peak |value| of a track as an order of magnitude (log10), or null when the
+ * track is empty or flat-zero — there is no magnitude to compare.
+ */
+function magnitude(track: (number | null)[]): number | null {
+  let peak = 0
+  for (const v of track) {
+    if (v !== null && Number.isFinite(v)) {
+      const a = Math.abs(v)
+      if (a > peak) peak = a
+    }
+  }
+  return peak > 0 ? Math.log10(peak) : null
+}
+
+// Split tracks onto a second y-axis once they span more than this many orders of
+// magnitude: below it a single shared axis reads fine; above it the smaller track
+// is flattened against the baseline by the larger one.
+const SPLIT_DECADES = 1
+
+/**
+ * Assign each series a y-scale: "y" (left axis) or "y2" (right axis). Tracks are
+ * split at their widest magnitude gap when that gap exceeds SPLIT_DECADES, with the
+ * smaller-magnitude tracks moving to "y2"; otherwise every track stays on "y".
+ * Flat-zero tracks have no magnitude, so they stay on the primary axis.
+ */
+function scaleKeys(): ("y" | "y2")[] {
+  const tracks = props.data.slice(1) as (number | null)[][]
+  const mags = tracks.map(magnitude)
+  const known = mags.filter((m): m is number => m !== null).sort((a, b) => a - b)
+  if (known.length < 2) return tracks.map(() => "y")
+  // The widest gap between adjacent magnitudes is the natural cut between "big" and
+  // "small" tracks; its midpoint is the threshold each track is measured against.
+  let gap = 0
+  let cut = 0
+  for (let i = 1; i < known.length; i++) {
+    if (known[i] - known[i - 1] > gap) {
+      gap = known[i] - known[i - 1]
+      cut = (known[i] + known[i - 1]) / 2
+    }
+  }
+  if (gap < SPLIT_DECADES) return tracks.map(() => "y")
+  return mags.map((m) => (m !== null && m < cut ? "y2" : "y"))
+}
+
 function trackSig(): string {
-  return props.series.map((s) => `${s.label}|${s.stroke}`).join(",")
+  const scales = scaleKeys()
+  return props.series.map((s, i) => `${s.label}|${s.stroke}|${scales[i]}`).join(",")
 }
 
 function options(width: number): uPlot.Options {
@@ -92,16 +138,24 @@ function options(width: number): uPlot.Options {
     ticks: { stroke: themeColor("--color-base-300", "#e5e7eb"), width: 1 },
     font: `11px ${family}`,
   }
+  const scales = scaleKeys()
+  const split = scales.includes("y2")
   return {
     width,
     height: props.height,
-    cursor: { y: false },
+    // No y crosshair, and no click-drag-to-zoom (uPlot's drag.setScale defaults
+    // on): the chart is a read-only readout — the playhead drives time, not a
+    // drag-selected zoom region.
+    cursor: { y: false, drag: { x: false, y: false } },
     scales: { x: { time: false } },
     series: [
-      {},
+      // x is simulation time, so the live legend's first column reads "Time"
+      // rather than uPlot's default "Value".
+      { label: "Time" },
       ...props.series.map(
-        (s): uPlot.Series => ({
+        (s, i): uPlot.Series => ({
           label: s.label,
+          scale: scales[i],
           stroke: s.stroke,
           width: 2,
           points: { show: false },
@@ -109,7 +163,15 @@ function options(width: number): uPlot.Options {
         }),
       ),
     ],
-    axes: [axis, { ...axis, size: 52 }],
+    // When tracks span orders of magnitude the small ones move to a right-hand
+    // axis ("y2"); its grid is suppressed so the two grids don't clash.
+    axes: split
+      ? [
+          axis,
+          { ...axis, size: 52 },
+          { ...axis, scale: "y2", side: 1, size: 52, grid: { show: false } },
+        ]
+      : [axis, { ...axis, size: 52 }],
   }
 }
 
@@ -173,4 +235,12 @@ watch(() => props.marker, syncMarker)
 :deep(.u-legend .u-value) {
   font-variant-numeric: tabular-nums;
 }
+/* Each track row toggles its line on click (⌘/Ctrl-click isolates it); the first
+   row is the Time readout and has no such handler. */
+:deep(.u-legend .u-series) {
+  cursor: pointer;
+}
+:deep(.u-legend .u-series:first-child) {
+  cursor: default;
+}
 </style>

src/model/io.ts

@@ -55,7 +55,8 @@ function isPolarity(value: unknown): value is Polarity {
 function isRule(value: unknown): value is Rule {
   if (!isObject(value)) return false
   if (value.kind === "constant") return isFiniteNumber(value.value)
-  if (value.kind === "proportional" || value.kind === "gap") return isFiniteNumber(value.factor)
+  if (value.kind === "proportional" || value.kind === "gap" || value.kind === "overflow")
+    return isFiniteNumber(value.factor)
   return false
 }
 
@@ -99,6 +100,14 @@ function nodeError(value: unknown, index: number): string | null {
   ) {
     return `${at}.rule must be a valid rule (constant/proportional/gap)`
   }
+  // The selection-time rationale (display only); any named node may carry one.
+  if (
+    kind !== "cloud" &&
+    value.description !== undefined &&
+    typeof value.description !== "string"
+  ) {
+    return `${at}.description must be a string`
+  }
   return null
 }
 
@@ -110,6 +119,9 @@ function linkError(value: unknown, index: number): string | null {
   if (typeof value.source !== "string") return `${at}.source must be a string`
   if (typeof value.target !== "string") return `${at}.target must be a string`
   if (!isPolarity(value.polarity)) return `${at}.polarity must be "+" or "-"`
+  if (value.description !== undefined && typeof value.description !== "string") {
+    return `${at}.description must be a string`
+  }
   return null
 }
 

src/model/simulation.ts

@@ -107,6 +107,19 @@ function evalRule(rule: Rule, links: InformationLink[], valueOf: (id: string) =>
         rule.factor * ((level ? valueOf(level.source) : 0) - (target ? valueOf(target.source) : 0))
       )
     }
+    case "overflow": {
+      // max(0, factor × (level − threshold)): a one-sided gap. The `+` input is the
+      // level, the `−` the threshold; it stays shut until the level passes it, so an
+      // overflow Flow spills only the excess. Clamping at 0 is what stops it running
+      // backwards below the threshold — gap can't, by design (it's bidirectional).
+      const level = links.find((link) => link.polarity === "+")
+      const threshold = links.find((link) => link.polarity === "-")
+      return Math.max(
+        0,
+        rule.factor *
+          ((level ? valueOf(level.source) : 0) - (threshold ? valueOf(threshold.source) : 0)),
+      )
+    }
   }
 }
 

src/model/types.ts

@@ -42,11 +42,15 @@ export interface Position {
  *                     (→ exponential growth/decay)
  *  - `gap`          — `factor × (level − target)`, where the `+` input is the
  *                     level and the `−` input the target. (→ goal-seeking)
+ *  - `overflow`     — `max(0, factor × (level − threshold))`: a one-sided `gap`
+ *                     that only fires once the `+` level exceeds the `−`
+ *                     threshold. (→ a spillway / hard ceiling)
  */
 export type Rule =
   | { kind: "constant"; value: number }
   | { kind: "proportional"; factor: number }
   | { kind: "gap"; factor: number }
+  | { kind: "overflow"; factor: number }
 
 /**
  * The run parameters for a simulation: integrate from `start` to `stop` in steps
@@ -78,6 +82,8 @@ export interface StockNode extends BaseNode {
   initialValue?: number
   /** Unit of the quantity, e.g. "°C", "people", "$" — shown beside the value (display only). */
   unit?: string
+  /** Why this Stock exists in *this* model — a free-text note surfaced on selection (display only). */
+  description?: string
 }
 
 /**
@@ -95,6 +101,8 @@ export interface FlowNode extends BaseNode {
   target: string
   /** How its rate is computed each instant (ADR-0004). Optional in the diagram phase. */
   rule?: Rule
+  /** Why this Flow exists in *this* model — a free-text note surfaced on selection (display only). */
+  description?: string
 }
 
 /**
@@ -106,6 +114,8 @@ export interface ConverterNode extends BaseNode {
   name: string
   /** How its value is computed each instant (ADR-0004). Optional in the diagram phase. */
   rule?: Rule
+  /** Why this Converter exists in *this* model — a free-text note surfaced on selection (display only). */
+  description?: string
 }
 
 /**
@@ -131,6 +141,8 @@ export interface InformationLink {
   /** Target node id — a Flow or Converter, never a Stock (ADR-0001). */
   target: string
   polarity: Polarity
+  /** Why this link exists in *this* model — a free-text note surfaced on selection (display only). */
+  description?: string
 }
 
 /** One saved document: the unit of save / export / reopen. */

src/store/model.ts

@@ -128,6 +128,28 @@ export const useModelStore = defineStore("model", () => {
     else node.unit = next
   }
 
+  /**
+   * Set (or clear) the free-text description on a named node or an Information
+   * Link — the "why this element exists" note surfaced on selection. Empty
+   * clears it; no-op when unchanged, so a blur with no edit doesn't burn undo.
+   */
+  function setDescription(id: string, text: string): void {
+    const next = text.trim() || undefined
+    const node = findNode(id)
+    if (node && node.kind !== "cloud") {
+      if (node.description === next) return
+      record()
+      if (next === undefined) delete node.description
+      else node.description = next
+      return
+    }
+    const link = model.value.infoLinks.find((l) => l.id === id)
+    if (!link || link.description === next) return
+    record()
+    if (next === undefined) delete link.description
+    else link.description = next
+  }
+
   /**
    * Set (or clear) how a Flow's rate or a Converter's value is computed (ADR-0004:
    * one of the fixed rules, never a formula). No-op when unchanged.
@@ -291,6 +313,7 @@ export const useModelStore = defineStore("model", () => {
     renameNode,
     setInitialValue,
     setUnit,
+    setDescription,
     setRule,
     setSimSpec,
     removeNode,