diff --git a/Content/CONTENT_GUIDE.md b/Content/CONTENT_GUIDE.md index 971a37e..d510ec2 100644 --- a/Content/CONTENT_GUIDE.md +++ b/Content/CONTENT_GUIDE.md @@ -48,7 +48,11 @@ explain: One or two sentences on why the answer is correct. ## Rules - Frontmatter keys: `id`, `track`, `module`, `title`, `summary`. `track` is one - of: foundations, core, dsp, sales, planning, analytics, engineering. + of: foundations, core, adops, dsp, sales, planning, analytics, engineering, ai, + or an industry vertical (`vertical-retail`, `vertical-cpg`, + `vertical-ecommerce`, `vertical-dtc`, `vertical-auto`, `vertical-finance`, + `vertical-travel`, `vertical-telecom`, `vertical-healthcare`, `vertical-qsr`, + `vertical-b2b`). - Structure each lesson as 3 to 5 short sections: a `# heading` then prose. - Include exactly one display-math block `$$ ... $$` where the concept has a formula. Keep LaTeX simple. Supported: greek (`\pi \mu \sigma \lambda \alpha @@ -92,10 +96,16 @@ explain: One or two sentences on why the answer is correct. - `codeLab` — read the algorithm behind a system - `didExplorer` — difference-in-differences lift - `yieldExplorer` — fill rate and yield - -Only `bidPlayground`/`auctionSimulator`, `reachFrequency`, and `experimentPower` -are interactive today. The rest render as a labeled placeholder, which is fine. -Reference whichever is most apt for the lesson. +- `pixelSetup` / `pixelWalkthrough` — step-by-step conversion-pixel setup walkthrough +- `pixelCalculators` / `trackingCalculators` — capture rate, dedup inflation, and discrepancy calculators + +Every type listed above renders as a live, interactive SwiftUI widget today; the +one exception is `monteCarlo`, which still renders as a labeled placeholder. The +registry that resolves a `:::widget ` directive to a view is +`Sources/BidLab/Widgets/WidgetRegistry.swift`. Reference whichever is most apt +for the lesson. If you add a new type, register it there and add it to the +`knownWidgets` whitelist in `Tests/BidLabCoreTests/ContentValidationTests.swift`, +or `Scripts/test.sh` will fail. ## Output diff --git a/README.md b/README.md index 004decd..cf15057 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,9 @@ The flight simulator for programmatic advertising. A native macOS app that teaches the math of programmatic by doing it: nine learning paths (Foundations and Programmatic Core, plus Ad Operations, DSP/Trader, Sales, Planning, -Analytics, Engineering, and AI in AdTech), 124 interactive lessons, 9 role -certification exams, a math-true bidding simulator, and a shareable credential. +Analytics, Engineering, and AI in AdTech) and eleven industry verticals, 225 +interactive lessons, 20 certification exams, a math-true bidding simulator, and a +shareable credential. Every concept is interactive and every number is real. Train the bid, the plan, the deal, the experiment, and the bidder itself, without spending a dollar of @@ -17,12 +18,14 @@ media. **▶ [Open the interactive web demo](https://scumunna.github.io/BidLab/)** — the *actual* BidLab engine running in your browser, free and on any device: drag a bid and run 50,000 auctions scored against the optimum, model reach and -frequency, and size an A/B test. No Mac required. +frequency, size an A/B test, and explore ten more (budget allocation, +attribution, yield, pacing, latency, conversion-pixel setup, and more). No Mac +required. [![BidLab web demo](web/public/og.png)](https://scumunna.github.io/BidLab/) Prefer the full experience? **[Download for macOS](https://github.com/scumunna/BidLab/releases)** -— 124 lessons, exams, spaced-repetition review, and shareable credentials — or +— 225 lessons, 20 exams, spaced-repetition review, and shareable credentials — or build from source below. > The web demo is a faithful TypeScript port of the pure `BidLabCore` Swift @@ -31,7 +34,7 @@ build from source below. ## Screenshots -**Learn — nine role-based paths and 124 cited, interactive lessons** +**Learn — nine role-based paths plus eleven industry verticals, 225 cited, interactive lessons** ![BidLab Learn surface](docs/screenshots/learn.png) @@ -62,23 +65,25 @@ build from source below. ## What is in here - **`BidLabCore`** (built as a SwiftPM-style library): a pure, UI-free Swift - engine validated by a known-answer test suite (2,500+ checks) covering pricing, + engine validated by a known-answer test suite (5,271 checks) covering pricing, auctions, probability, statistics, reach and frequency, budget allocation, pacing, a seeded market simulation, scoring, analytics (power, difference-in- - differences, adstock, saturation, OLS), DSP systems (latency, queueing), and - the lesson parser. + differences, adstock, saturation, OLS), DSP systems (latency, queueing), + conversion tracking, and the lesson parser. - **The app** (`Sources/BidLab`): a SwiftUI shell with nine surfaces (Learn, Review, Industries, Trading Floor, Tools, Exams, Progress, Explorable, and Settings), an original design system, interactive widgets, a native math renderer, the "open the hood" transparency panel, an embedded SQLite SQL lab, branded PNG/CSV/JSON export, and progress with a shareable certificate. -- **Content** (`Content/Lessons/*.md`): 124 authored, cited lessons in an original +- **Content** (`Content/Lessons/*.md`): 225 authored, cited lessons in an original Markdown-flavored format, parsed at launch from the app bundle. See `Content/CONTENT_GUIDE.md` for the format. -- **Web demo** (`web/`): a Vite + React + TypeScript reimplementation of the hero - explorables (Trading Floor, Reach & Frequency, A/B Power), deployed free to - GitHub Pages. The math is a faithful port of `BidLabCore`, verified against the - Swift engine in a golden-master test, and the build/deploy is automated in +- **Web demo** (`web/`): a Vite + React + TypeScript reimplementation of thirteen + interactive explorables (the Trading Floor plus Reach & Frequency, A/B Power, + Budget Allocator, Latency, Margin, Pixel Setup, Attribution, Forecast, Yield, + Pricing, Adstock, and Distribution), deployed free to GitHub Pages. The math is + a faithful port of `BidLabCore`, verified against the Swift engine in + golden-master tests (180 web tests; the engine is gated at 100% coverage), and the build and deploy are automated in `.github/workflows/pages.yml`. ## Building and running @@ -88,11 +93,20 @@ Xcode). This project builds entirely with `swiftc` (no full Xcode required), because the Command Line Tools on the original machine shipped a broken SwiftPM. ```sh -./Scripts/test.sh # build the core and run the test suite (2,500+ checks) +./Scripts/test.sh # build the core and run the test suite (5,271 checks) ./Scripts/build.sh # build the app -> build/BidLab.app open build/BidLab.app # run it ``` +For the web demo: + +```sh +cd web +npm install +npm test # run the engine + acceptance test suite (180 checks) +npm run dev # serve the demo locally +``` + To produce a distributable disk image: ```sh @@ -111,8 +125,13 @@ hdiutil create -volname BidLab -srcfolder build/BidLab.app -ov -format UDZO buil ## Status -BidLab 1.0. All nine paths are complete (124 lessons), every widget is -interactive, and the product has been verified running in the live environment. +BidLab is feature-complete: all nine role paths and eleven industry verticals are +authored (225 lessons, 20 certification exams), every widget is interactive, and +the free web demo is live on GitHub Pages. The pure engines are covered to 100% +(web) and 100% of reachable code (native), enforced by CI coverage gates, across +5,271 native and 180 web known-answer checks; see +[docs/COVERAGE.md](docs/COVERAGE.md) and [docs/ACCEPTANCE.md](docs/ACCEPTANCE.md). +Latest release: [v1.1.1](https://github.com/scumunna/BidLab/releases). ## License diff --git a/docs/ACCEPTANCE.md b/docs/ACCEPTANCE.md index a003efa..92392e9 100644 --- a/docs/ACCEPTANCE.md +++ b/docs/ACCEPTANCE.md @@ -16,12 +16,14 @@ A reproducible, deterministic acceptance pass over every major capability of the | Layer | What it proves | Scenarios | Result | |---|---|---|---| | **Engine acceptance suite** (`web/src/eval/acceptance.test.ts`) | Every engine capability: golden + invariant + edge | **100** | ✅ 100 / 100 | -| Web unit suite (`web/src/engine/*.test.ts`) | Golden parity vs the compiled Swift engine | 47 | ✅ 47 / 47 | +| Web engine suite (`web/src/engine/*.test.ts`) | Golden parity vs the compiled Swift engine + 100% engine boundary coverage | 80 | ✅ 80 / 80 | | Live UI run (Playwright, headless) | Entry, routing, the hero in 3 modes, onboarding, all explorables, the pixel widget, responsiveness @375px | 20 | ✅ 20 / 20 | -| Native known-answer suite (`./Scripts/test.sh`) | Swift engine + all lessons/exams/widgets | 5,127 | ✅ 5,127 / 5,127 | +| Native known-answer suite (`./Scripts/test.sh`) | Swift engine + all lessons/exams/widgets | 5,271 | ✅ 5,271 / 5,271 | **The complete set passed on the first run and again on rerun (stable).** No failures occurred, so the fix-and-rerun loop completed with no changes required — the product already cleared the bar. +Both pure engines are additionally **gated to 100% coverage in CI**: the web engine via `vitest` v8 (`.github/workflows/web.yml`) and `BidLabCore` via `llvm-cov` of reachable code (`.github/workflows/ci.yml`). See [COVERAGE.md](COVERAGE.md). + ## The 100 acceptance scenarios, by capability Each row is a numbered, named `it(...)` in `web/src/eval/acceptance.test.ts`; that file is the line-by-line evidence. @@ -46,11 +48,11 @@ Each row is a numbered, named `it(...)` in `web/src/eval/acceptance.test.ts`; th ## Reproduce ```sh -# Engine acceptance + web unit (100 + 47), deterministic: -cd web && npm test # -> 147 passed +# Engine acceptance + web engine suites (100 + 80), deterministic: +cd web && npm test # -> 180 passed # Native engine + all curriculum (lessons, exams, widgets): -./Scripts/test.sh # -> all 5,127 checks passed +./Scripts/test.sh # -> all 5,271 checks passed ``` The web demo's numbers are not illustrative — they are the *same* engine, asserted equal to the native macOS app. That parity is the whole point: what a CEO clicks in the browser is the production math. diff --git a/web/src/App.tsx b/web/src/App.tsx index be65c0c..6ea27bd 100644 --- a/web/src/App.tsx +++ b/web/src/App.tsx @@ -150,7 +150,7 @@ export default function App() { matches the native app bit-for-bit).

- The full app adds 124 interactive lessons across 9 roles and 11 industry verticals, certification exams, spaced-repetition + The full app adds 225 interactive lessons across 9 roles and 11 industry verticals, 20 certification exams, spaced-repetition review, and shareable credentials.{' '} See the project on GitHub →