One simulated year group, 120 students. Educate the same 30% of them, but change who: + the fake reaches 82% of the school with no program, + 58% educating at random, and + 6% educating the best‑connected students.
+ Illustrative model, not validated +One simulated year group, 120 students. Educate the same 30% of them, but change who: + the fake reaches 82% of the school with no program, + 58% educating at random, and + 6% educating the best‑connected students.
+ Illustrative model, not validated +| ` headers (evolved from the existing + ComparisonTable), collapsed behind a disclosure reachable by + keyboard. +- [ ] One `aria-live="polite"` region announces results after each + successful run ("Updated: No program 83 percent, ..."), on pause, + on scrub release, and at playback end ("Final: ..."); it does not + announce every round during playback. +- [ ] FocusModal: `role="dialog"` `aria-modal="true"`, labelled by the + panel name, focus moves in on open, is trapped, Esc closes, focus + returns to the opener. +- [ ] Popovers (About, panel editor, export menu) follow the same + open/trap/restore rules as menus or dialogs per their role. +- [ ] ErrorBanner and inline 400 errors use `role="alert"`. +- [ ] Touch targets are at least 44x44 px on mobile (player buttons, + kebabs, chips, strip items); node hit halos at least 24 px. +- [ ] ``, landmarks: `header` (app bar), `main`, `footer`. +- [ ] Zoom to 200% at 1366 px wide loses no content or functionality + (panels reflow to the mobile stack). + +--- + +## 9. Responsive behavior + +Breakpoint: 760 px (one breakpoint only). + +Mobile (< 760 px): +- App bar keeps wordmark + theme + source; DisclaimerBadge hides, replaced + by the DisclaimerNote line under the hero. +- MobileScoreStrip appears: sticky under the app bar, horizontally + scrollable pill chips, one per panel (short label + colored %); tapping + a chip smooth-scrolls to its panel (instant under reduced motion). +- PanelGrid stacks single-column; toolbar stays one row (Export collapses + to an icon button if needed). +- PlayerBar fixes to the bottom edge (12 px inset, lifted shadow); step + buttons and the speed pill hide, leaving replay, play/pause, scrubber, + round counter. Page bottom padding clears it. +- Lower grid stacks: chart, then controls. Control rows go single-column + (label above slider, value right-aligned). +- FocusModal becomes a full-screen sheet. +- No horizontal scrolling at 320 px width; the strip is the only + horizontally scrollable element. + +Desktop >= 760 px matches the wireframe; the panel grid is +`repeat(3, 1fr)` for up to 3 panels, wraps to two rows of up to 3 beyond. + +--- + +## 10. Implementation slices (ordered) + +Each slice leaves the app shippable. + +1. **API topology**: add `POST /api/scenario` (config + strategy in, + result + edges out) in Go, tygo regen, tests for edge determinism. +2. **Store + URL**: `useSimStore` with preset loading, URL parse/serialize, + debounced parallel runs, atomic swap, keep-last-good error states. +3. **Static dashboard**: app bar, hero with live numbers, theme system and + tokens, panel cards with seeded d3-force NetworkView at final state, + legend, footer. (The page now beats the parity page; ComparisonTable + becomes the collapsed ResultsTable.) +4. **Playback**: usePlayback, PlayerBar, round-state rendering, autoplay + once, reduced-motion path, keyboard map. +5. **Reach chart**: overlaid cumulative curves, accents, playhead synced + to round. +6. **Controls**: lever sliders, advanced fields, seed rerolls, inline 400 + handling, ErrorBanner. +7. **Panel management**: add/duplicate/rename/remove, PanelEditorPopover + with override chips, 6-panel cap. +8. **Focus modal** with docked player and URL focus state. +9. **Node tooltip** with cross-panel echo and touch hit halos. +10. **Mobile pass**: score strip, fixed player, stacking, touch targets. +11. **Export**: JSON, CSV, PNG snapshot. +12. **Accessibility audit**: walk the section 8 checklist, fix, record + results in the PR description. + +Post-M3 (specced hooks, not built): `POST /api/optimize` goal-seek UI, +animated WebM/GIF export, additional study presets. + +--- + +## 11. Rejected alternatives + +- Single large network with strategy tabs: hides the comparison behind + clicks; the side-by-side comparison is the message. +- Fixed three-strategy panels only: cannot express budget or world + variations the dynamic-panel model needs. +- Fully independent config per panel: breaks layout comparability and + bloats URL and editor; overrides express the same power against a shared + base. +- Hardcoded study copy: blocks reuse for other research questions; preset + file chosen instead. +- Expand-in-place or routed focus view: modal chosen by user; routing + would pull in Vue Router for one interaction. +- Share button with clipboard toast: user chose address-bar-only sharing. +- Explicit Run button (and hybrid auto/manual): kills the + cause-and-effect immediacy that makes the lever visceral. +- Looping autoplay: hostile motion while reading; play-once chosen. +- Per-panel players: panels drift out of sync and the comparison dies. +- Per-panel sparklines and numbers-only metrics: hard to compare; one + overlaid chart chosen. +- Budget sweep / optimizer in M3: doubles scope; reserved as API hook. +- Animated GIF/WebM export in M3: as much work as the whole animation + feature; PNG + live share URL cover the need. +- Dark-only or light-only theme: both ship, prototype renders exist for + both and the toggle is cheap. +- Canvas/WebGL network rendering: SVG is ample at 120 nodes x 6 panels + and is easier to theme, hit-test, and export. +- Batch `/api/scenarios` endpoint: per-panel `POST /api/scenario` with + `Promise.all` is simpler and lets panels rerun independently. +- Base64 state blob in URL: readable repeated params chosen for a FOSS + demo; blob survives only as a fallback idea if URLs ever exceed limits. +- Fully focusable network nodes for screen readers: 120 tab stops x N + panels is worse than the table; aria-hidden SVG + live region + table + chosen. +- Pinia and Vue Router: not required by this design; module-scope + composable store and modal focus suffice. diff --git a/internal/api/api.go b/internal/api/api.go index 11d7107..080bd64 100644 --- a/internal/api/api.go +++ b/internal/api/api.go @@ -19,6 +19,23 @@ type ComparisonResponse struct { Results []engine.Result `json:"results"` } +// ScenarioRequest is the body of POST /api/scenario: one panel's effective +// config plus its strategy. +type ScenarioRequest struct { + Config engine.Config `json:"config"` + Strategy engine.Strategy `json:"strategy"` +} + +// ScenarioResponse carries everything one dashboard panel needs: the +// echoed config, the cascade result, and the network topology as +// [from, to] node-index pairs (deterministic from the config's graph +// fields) for the frontend's force layout. +type ScenarioResponse struct { + Config engine.Config `json:"config"` + Result engine.Result `json:"result"` + Edges [][2]int `json:"edges"` +} + // errorResponse is the JSON shape of every non-2xx body. type errorResponse struct { Error string `json:"error"` @@ -31,6 +48,7 @@ func NewServer() http.Handler { mux := http.NewServeMux() mux.HandleFunc("GET /api/config/default", handleDefaultConfig) mux.HandleFunc("POST /api/comparison", handleComparison) + mux.HandleFunc("POST /api/scenario", handleScenario) return mux } @@ -62,6 +80,30 @@ func handleComparison(w http.ResponseWriter, r *http.Request) { writeJSON(w, http.StatusOK, ComparisonResponse{Config: config, Results: results}) } +func handleScenario(w http.ResponseWriter, r *http.Request) { + decoder := json.NewDecoder(r.Body) + decoder.DisallowUnknownFields() + var request ScenarioRequest + if err := decoder.Decode(&request); err != nil { + writeError(w, http.StatusBadRequest, fmt.Errorf("invalid request: %w", err)) + return + } + + result, err := engine.RunScenario(request.Config, request.Strategy) + if err != nil { + writeError(w, http.StatusBadRequest, err) + return + } + // Building the graph again for its edges costs ~25us (seeded, so it is + // the identical world the scenario ran in). + edges, err := engine.GraphEdges(request.Config) + if err != nil { + writeError(w, http.StatusBadRequest, err) + return + } + writeJSON(w, http.StatusOK, ScenarioResponse{Config: request.Config, Result: result, Edges: edges}) +} + // writeJSON marshals first and writes after, so an encoding failure can // still become a clean 500 instead of a half-written body. func writeJSON(w http.ResponseWriter, status int, payload any) { diff --git a/internal/api/scenario_test.go b/internal/api/scenario_test.go new file mode 100644 index 0000000..546ab5d --- /dev/null +++ b/internal/api/scenario_test.go @@ -0,0 +1,87 @@ +package api + +import ( + "encoding/json" + "net/http" + "testing" + + "github.com/JustinZeus/spreadlab/internal/engine" +) + +func postScenario(t *testing.T, request ScenarioRequest) *json.Decoder { + t.Helper() + body, err := json.Marshal(request) + if err != nil { + t.Fatal(err) + } + recorder := serve(t, http.MethodPost, "/api/scenario", body) + if recorder.Code != http.StatusOK { + t.Fatalf("status = %d, want %d; body: %s", recorder.Code, http.StatusOK, recorder.Body) + } + return json.NewDecoder(recorder.Body) +} + +func TestScenarioEndpointReturnsResultAndTopology(t *testing.T) { + request := ScenarioRequest{Config: engine.DefaultConfig(), Strategy: engine.StrategyMostConnected} + + var response ScenarioResponse + if err := postScenario(t, request).Decode(&response); err != nil { + t.Fatal(err) + } + + if response.Result.NumReached != 7 { // the pinned golden value + t.Errorf("NumReached = %d, want 7", response.Result.NumReached) + } + if response.Config != request.Config { + t.Errorf("config not echoed: got %+v", response.Config) + } + if len(response.Edges) == 0 { + t.Fatal("no edges returned") + } + for _, edge := range response.Edges { + if edge[0] >= edge[1] || edge[1] >= request.Config.NumStudents { + t.Fatalf("invalid edge %v", edge) + } + } + + // Determinism across requests is the shared-URL guarantee. + var repeat ScenarioResponse + if err := postScenario(t, request).Decode(&repeat); err != nil { + t.Fatal(err) + } + if len(repeat.Edges) != len(response.Edges) || repeat.Edges[0] != response.Edges[0] { + t.Error("edges differ across identical requests") + } +} + +func TestScenarioEndpointRejectsBadRequests(t *testing.T) { + valid := engine.DefaultConfig() + invalid := valid + invalid.ForwardProb = 2.0 + + encode := func(request ScenarioRequest) []byte { + body, err := json.Marshal(request) + if err != nil { + t.Fatal(err) + } + return body + } + + tests := []struct { + name string + body []byte + }{ + {name: "not json", body: []byte("not json")}, + {name: "unknown field", body: []byte(`{"config":{},"strategy":"none","extra":1}`)}, + {name: "unknown strategy", body: encode(ScenarioRequest{Config: valid, Strategy: "telepathy"})}, + {name: "invalid config values", body: encode(ScenarioRequest{Config: invalid, Strategy: engine.StrategyNone})}, + } + for _, testCase := range tests { + t.Run(testCase.name, func(t *testing.T) { + recorder := serve(t, http.MethodPost, "/api/scenario", testCase.body) + if recorder.Code != http.StatusBadRequest { + t.Errorf("status = %d, want %d; body: %s", recorder.Code, http.StatusBadRequest, recorder.Body) + } + }) + } +} diff --git a/internal/engine/graph.go b/internal/engine/graph.go index e6b57e7..a2c6cf8 100644 --- a/internal/engine/graph.go +++ b/internal/engine/graph.go @@ -48,3 +48,18 @@ func (g *Graph) Degree(u int) int { return len(g.adj[u]) } // Neighbors returns u's neighbours in insertion order. The slice is the // graph's own storage: callers must not modify it. func (g *Graph) Neighbors(u int) []int { return g.adj[u] } + +// Edges returns every undirected edge exactly once as a [from, to] pair +// with from < to, in deterministic node order. The slice is freshly +// allocated; callers may keep it. +func (g *Graph) Edges() [][2]int { + edges := make([][2]int, 0, g.edges) + for node := range g.NumNodes() { + for _, neighbor := range g.adj[node] { + if node < neighbor { + edges = append(edges, [2]int{node, neighbor}) + } + } + } + return edges +} diff --git a/internal/engine/graph_test.go b/internal/engine/graph_test.go index 56124b3..2e14acb 100644 --- a/internal/engine/graph_test.go +++ b/internal/engine/graph_test.go @@ -74,3 +74,56 @@ func TestGraphNeighborsAndDegree(t *testing.T) { t.Error("HasEdge(1, 2) = true, want false") } } + +func TestGraphEdgesListsEveryEdgeOnce(t *testing.T) { + graph := NewGraph(4) + graph.AddEdge(2, 1) // insertion order must not matter; pairs come out from < to + graph.AddEdge(0, 1) + graph.AddEdge(3, 0) + + want := [][2]int{{0, 1}, {0, 3}, {1, 2}} + if got := graph.Edges(); !slices.Equal(got, want) { + t.Errorf("Edges() = %v, want %v", got, want) + } +} + +func TestGraphEdgesMatchesGeneratedGraph(t *testing.T) { + graph, err := HolmeKim(60, 3, 0.45, newRand(17)) + if err != nil { + t.Fatal(err) + } + + edges := graph.Edges() + if len(edges) != graph.NumEdges() { + t.Fatalf("len(Edges()) = %d, want NumEdges() = %d", len(edges), graph.NumEdges()) + } + for _, edge := range edges { + from, to := edge[0], edge[1] + if from >= to { + t.Errorf("edge %v: want from < to", edge) + } + if to >= graph.NumNodes() { + t.Errorf("edge %v: endpoint out of range", edge) + } + if !graph.HasEdge(from, to) { + t.Errorf("edge %v not present in adjacency", edge) + } + } +} + +func TestGraphEdgesDeterministicFromConfig(t *testing.T) { + first, err := GraphEdges(DefaultConfig()) + if err != nil { + t.Fatal(err) + } + second, err := GraphEdges(DefaultConfig()) + if err != nil { + t.Fatal(err) + } + if !slices.Equal(first, second) { + t.Error("GraphEdges() differs across identical configs") + } + if len(first) == 0 { + t.Error("GraphEdges() returned no edges") + } +} diff --git a/internal/engine/scenario.go b/internal/engine/scenario.go index 89262a4..37d2e59 100644 --- a/internal/engine/scenario.go +++ b/internal/engine/scenario.go @@ -60,6 +60,18 @@ type Result struct { ReachedPct float64 `json:"reachedPct"` } +// GraphEdges builds the world's social network from the config's graph +// fields and returns its undirected edge list. The same config always +// yields the same edges (seeded generator), so the API can expose +// topology separately without every Result carrying it. +func GraphEdges(config Config) ([][2]int, error) { + graph, err := HolmeKim(config.NumStudents, config.EdgesPerNode, config.TriangleProb, newRand(config.GraphSeed)) + if err != nil { + return nil, err + } + return graph.Edges(), nil +} + // RunScenario builds the world the config describes (network plus edge // thresholds), picks the educated students per strategy, and runs the // cascade. Scenarios with the same config share the same world, so diff --git a/tygo.yaml b/tygo.yaml index 7db3727..024b496 100644 --- a/tygo.yaml +++ b/tygo.yaml @@ -11,7 +11,8 @@ packages: include_files: - "api.go" frontmatter: | - import type { Config, Result } from "./engine"; + import type { Config, Result, Strategy } from "./engine"; type_mappings: engine.Config: "Config" engine.Result: "Result" + engine.Strategy: "Strategy" diff --git a/web/src/types/api.ts b/web/src/types/api.ts index 81f10f3..34811ec 100644 --- a/web/src/types/api.ts +++ b/web/src/types/api.ts @@ -1,5 +1,5 @@ // Code generated by tygo. DO NOT EDIT. -import type { Config, Result } from "./engine"; +import type { Config, Result, Strategy } from "./engine"; ////////// // source: api.go @@ -18,3 +18,22 @@ export interface ComparisonResponse { config: Config; results: Result[]; } +/** + * ScenarioRequest is the body of POST /api/scenario: one panel's effective + * config plus its strategy. + */ +export interface ScenarioRequest { + config: Config; + strategy: Strategy; +} +/** + * ScenarioResponse carries everything one dashboard panel needs: the + * echoed config, the cascade result, and the network topology as + * [from, to] node-index pairs (deterministic from the config's graph + * fields) for the frontend's force layout. + */ +export interface ScenarioResponse { + config: Config; + result: Result; + edges: number /* int */[][]; +} |
|---|