Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
170 commits
Select commit Hold shift + click to select a range
368aae4
Add spacing, type, radius and motion tokens to the v2 theme block
YuZh98 Jul 25, 2026
c738e34
Use design tokens for spacing, type and radius in the note, tag and s…
YuZh98 Jul 25, 2026
fcfed39
Use design tokens for spacing, type, radius and motion in CardView an…
YuZh98 Jul 25, 2026
bd50550
Use spacing and radius tokens in the remaining v2 component markup
YuZh98 Jul 25, 2026
7502676
Document the v2 design-token rule
YuZh98 Jul 25, 2026
1ec6a4e
test: add seeded generative suite for variable-graph resolution
YuZh98 Jul 25, 2026
88bde00
test: add seeded generative suite for interchange round-trips
YuZh98 Jul 25, 2026
2cefc3e
test: add seeded generative suite for progress semantics
YuZh98 Jul 25, 2026
ec88c10
test: add seeded generative suite for expression evaluation
YuZh98 Jul 25, 2026
f69e5a6
test: make the variable-graph simulation fail on a degenerate generator
YuZh98 Jul 25, 2026
468a1da
test: check progress counts at every step and unparenthesised precedence
YuZh98 Jul 25, 2026
437328e
Add Code of Conduct and scope CONTRIBUTING
YuZh98 Jul 25, 2026
3120b66
docs: add architecture, design system, and interchange format guides
YuZh98 Jul 25, 2026
5cc5cd7
docs: qualify absolute statements in the architecture and design syst…
YuZh98 Jul 25, 2026
7b0eb0d
Style the macOS disk image installer window
YuZh98 Jul 25, 2026
ee3eec4
docs: add a macOS install and DMG build guide
YuZh98 Jul 25, 2026
b7912f7
docs: add the grand-tour example notebook
YuZh98 Jul 25, 2026
e2cd49d
docs: lead the README with the differentiator and document data location
YuZh98 Jul 25, 2026
2c51209
docs: state import validation and reader privacy accurately
YuZh98 Jul 25, 2026
491bf48
Merge revu-learnings: style round learned from revu-swift
YuZh98 Jul 25, 2026
99e8d55
docs: show four themes in the README
YuZh98 Jul 25, 2026
46327e9
docs: retake theme screenshots with a compact card layout
YuZh98 Jul 25, 2026
bc3f648
Add the Terminal theme and a quant-terminal showcase example
YuZh98 Jul 25, 2026
4baf355
Polish the dark-green theme round: hover glow, emphasis colors, zoom …
YuZh98 Jul 25, 2026
227611b
Seed new builtin card types into existing databases
YuZh98 Jul 25, 2026
4e7b4ed
docs: stage the current round under Unreleased in the changelog
YuZh98 Jul 25, 2026
9e378fb
Carry Card.typeId through export and import
YuZh98 Jul 25, 2026
662b9f6
Make empty check-style lists vacuously complete
YuZh98 Jul 25, 2026
54ac8ec
Scope the no-native-drag claim to exclude Factory chips
YuZh98 Jul 25, 2026
63018a7
Add the study-cursor decision modules
YuZh98 Jul 25, 2026
338d0cd
Drive a Study session from the keyboard
YuZh98 Jul 25, 2026
b832a54
Regenerate the Reader template with the keyboard-first Study
YuZh98 Jul 25, 2026
64d74db
Document the keyboard-first Study
YuZh98 Jul 25, 2026
2d57754
Keep the study cursor on what the reader can see and act on
YuZh98 Jul 25, 2026
df9d3be
Regenerate the Reader template
YuZh98 Jul 25, 2026
47d7ede
Map the keyboard modules and refresh the test count
YuZh98 Jul 25, 2026
a09dc26
Drop the study cursor when its card leaves the page
YuZh98 Jul 25, 2026
921ef3a
Correct the session-state lifetime in the code map
YuZh98 Jul 25, 2026
a907628
Regenerate the Reader template
YuZh98 Jul 25, 2026
a075289
docs: fix stale drag-engine claims and test count in CODE-MAP/CHANGELOG
YuZh98 Jul 25, 2026
a39aa80
Merge v030-prep: correctness fixes and keyboard-first Study
YuZh98 Jul 25, 2026
4090781
Scale the store preview to the sidebar panel
YuZh98 Jul 26, 2026
1b59273
Answer study keys only where the reader can act
YuZh98 Jul 26, 2026
5daca60
Make the study shortcut overlay modal and house-only
YuZh98 Jul 26, 2026
a5f2049
Divide viewport pixels by the app zoom before writing them as styles
YuZh98 Jul 26, 2026
eb21716
Give the exported Reader the zoom its own help overlay advertises
YuZh98 Jul 26, 2026
b8208fe
Print at 100% however the app is zoomed
YuZh98 Jul 26, 2026
08a0071
Convert the remaining viewport pixels the components write as styles
YuZh98 Jul 26, 2026
67557be
Guard boot hydration against a corrupt seeded-builtins ledger
YuZh98 Jul 26, 2026
119579d
Make unterminated-string tokenization linear
YuZh98 Jul 26, 2026
49be938
Replace raw pixel values with spacing tokens in kb-hint and kfocus
YuZh98 Jul 26, 2026
cb20622
Fix the tokenizer perf test's pathological input
YuZh98 Jul 26, 2026
21f3df1
Make the study cursor discoverable and legible
YuZh98 Jul 26, 2026
b3485a8
Show where a placed card lands, and let Reset clear the search
YuZh98 Jul 26, 2026
f65d4fc
Preview a store product at its own width, not the room's
YuZh98 Jul 26, 2026
8e635b0
Fix the first-run copy and the terminal theme chip
YuZh98 Jul 26, 2026
c8cef79
Make the shortcut overlay modal to focus, and list the arrow keys
YuZh98 Jul 26, 2026
9de050f
Mark the ring's accent-stripe literal token-exempt
YuZh98 Jul 26, 2026
37b7539
Let clicks and paper through the pinned study hint
YuZh98 Jul 26, 2026
bdca60a
Bring the token counts and the code map up to date
YuZh98 Jul 26, 2026
2703982
Merge review-fixes: close the code review's bugs and top UX frictions
YuZh98 Jul 26, 2026
e1fc8fd
feat(choice): add isChoiceCorrect and an optional score() slot hook
claude Oct 18, 2026
3d0a84a
feat(debounce): add flush, cancel and pending controls
claude Oct 18, 2026
1c65baf
fix(db-map): persist card width so resized cards survive reload
claude Oct 18, 2026
52a93cd
schema(share): embed the author's notebook id as the payload docId
claude Oct 18, 2026
e3390c1
feat(reader): add a localStorage progress store keyed by card content
claude Oct 18, 2026
60f7180
feat(reader): build a results summary from reader progress
claude Oct 18, 2026
85189e4
feat(autosave): add hydration-gated autosave channels
claude Oct 18, 2026
1f4cda0
fix(db): serialize SQLite I/O and make saves atomic batches
claude Oct 18, 2026
399172c
feat(reader): remember each student's progress and export results
claude Oct 18, 2026
59781db
fix(reader): load progress when only a storage key is given
claude Oct 18, 2026
9eac79e
fix(reader): keep the results copy fallback text in sync
claude Oct 18, 2026
344c007
feat(tauri): hold user quits until the frontend flushed its saves
claude Oct 18, 2026
44f15f1
fix(app): never lose an edit on switch, startup, close or undo
claude Oct 18, 2026
b81cb18
ci: run the v2 job on Node 22 for the node:sqlite tests
claude Oct 18, 2026
8de9dc2
fix(app): drop a pre-hydration selection when the stored notebook loads
claude Oct 18, 2026
397991c
fix(db): fall back to column defaults inside the atomic save batch
claude Oct 18, 2026
eac8a8b
feat(expr): add strict parseExpr validator alongside evalExpr
claude Oct 18, 2026
fceac18
fix(db): skip an unreadable reader-state row instead of failing load
claude Oct 18, 2026
20d3ba2
feat(rng): add seeded mulberry32 generator and step-grid draws
claude Oct 18, 2026
fa91a6a
feat(numeric-input): add strict parser for typed numeric answers
claude Oct 18, 2026
dc3269a
feat(slots): add problem slot for randomized numeric practice
claude Oct 18, 2026
ae7d52a
feat(json-io): structured validation issues; check props, verbs, tags
claude Oct 18, 2026
14f6394
fix(rng): keep drawParam finite on ranges that overflow the step count
claude Oct 18, 2026
44e9f62
fix(slots): reopen a solved problem when a card variable moves its an…
claude Oct 18, 2026
cfc56d3
feat(schema): publish the notebook JSON Schema with a sync test
claude Oct 18, 2026
ab08ba2
feat(ai): prompt kit and slot catalog for writing notebooks with an LLM
claude Oct 18, 2026
52e4f76
feat(import): human-readable import problems with fix hints
claude Oct 18, 2026
5092df3
feat(ui): ImportReport and FromAiModal components
claude Oct 18, 2026
a54a7f6
feat(topbar): turn the bare + into a new-notebook menu
claude Oct 18, 2026
dd384ad
fix(ai): say which fields render markdown and math
claude Oct 18, 2026
2259eef
docs: add FORMAT.md, the human-readable interchange format spec
claude Oct 18, 2026
1a09a33
fix(app): save edits made while the startup load is still running
claude Oct 18, 2026
ff36158
test: guard the Reader bundle boundary; tighten review findings
claude Oct 18, 2026
a95bdac
fix(ui): hand FromAiModal's parsed JSON to the host as plain data
claude Oct 18, 2026
5dc50c5
fix(import): look up user-supplied keys as own properties only
claude Oct 18, 2026
fd62b1c
fix(slots): keep the full keyboard on the problem answer field
claude Oct 18, 2026
b74ea9d
fix(import): find the notebook in replies whose prose has braces
claude Oct 18, 2026
1de03e4
fix(ai): warn that -x^2 is (-x)^2 and that ** is no operator
claude Oct 18, 2026
5e6c1a5
fix(topbar): keep the + menu's navigation keys out of App shortcuts
claude Oct 18, 2026
9db71d4
merge: W1 durability core (atomic serialized saves, flush on close)
claude Oct 18, 2026
9df8a28
merge: W2 Reader remembers progress, results export
claude Oct 18, 2026
14594d6
merge: W3 problem slot for randomized practice
claude Oct 18, 2026
503f190
merge: W4 JSON Schema, import hints, AI prompt kit
claude Oct 18, 2026
be1964b
feat: wire From AI and import reports into the app; schema learns pro…
claude Oct 18, 2026
379349d
schema: persist a local draft flag on cards
claude Oct 18, 2026
56c1786
feat: add helpers to mark, list and step through draft cards
claude Oct 18, 2026
50c0bca
fix(choice): never paint an ungraded pick as wrong
claude Oct 18, 2026
09bb436
feat(card-types): add Guided Explore, Worked Example, Practice Set
claude Oct 18, 2026
d846210
feat(factory): add a Step-by-step slot effect
claude Oct 18, 2026
4a8b434
feat: review cards made From AI as drafts before sharing
claude Oct 18, 2026
a120c94
feat(app): seed each built-in card type once, so new ones reach users
claude Oct 18, 2026
ff02133
docs(examples): add a percent change lesson built from guided cards
claude Oct 18, 2026
1b147a4
feat(card-types): explain how to adapt each guided built-in
claude Oct 18, 2026
9874a0b
test: pin draft review edges for filters, redo and edit sessions
claude Oct 18, 2026
23a6888
feat: add the version-history policy for notebook snapshots
claude Oct 18, 2026
4e2c18d
schema: store notebook versions in a local snapshots table
claude Oct 18, 2026
b491b25
feat: decide when a notebook gets an automatic version
claude Oct 18, 2026
60325ff
feat: keep notebook versions and restore them from the sidebar
claude Oct 18, 2026
6f71340
fix(versions): harden restore and keep snapshot failures out of saves
claude Oct 18, 2026
95111f5
fix(versions): keep the version a long-idle notebook was still at
claude Oct 18, 2026
87da65e
merge: W6 AI drafts review flow and W7 version history
claude Oct 18, 2026
325f9ac
merge: W5 guided card types, step-by-step verb, builtin seeding, exam…
claude Oct 18, 2026
9d50bcf
fix: integrate wave 2 — seed test mock, chart ranges, reviewed label
claude Oct 18, 2026
ac1765b
build(reader): regenerate the share template; CI checks it stays fresh
claude Oct 18, 2026
09e2eb3
docs: document the 0.3.0 round (living handout, From AI, durability)
claude Oct 18, 2026
159fe7b
fix(import): replace lone surrogates before text can reach SQLite
claude Oct 18, 2026
0caa061
fix(share): escape every < in the embedded payload, not only </
claude Oct 18, 2026
a17ea51
fix(share): namespace shared files' progress by a per-install id
claude Oct 18, 2026
7b358be
fix(reader): show a readable page when a shared file cannot open
claude Oct 18, 2026
cbe6fab
fix(share): hold back Share and Export while the notebook fails valid…
claude Oct 18, 2026
bcdcda7
fix(reader): keep the shared file off Google Fonts
claude Oct 18, 2026
900a12e
fix(reader): lay the shared Reader out for phones
claude Oct 18, 2026
0b0efec
fix(ai-prompt): teach the problem slot's rules in the AI kit
claude Oct 18, 2026
736cde4
test(reader): unmount the booted Reader with its own svelte instance
claude Oct 18, 2026
f617854
fix(import-hints): suggest slot types for misspelled and plural aliases
claude Oct 18, 2026
db416eb
fix(import-hints): list schema problems behind a trailing comma
claude Oct 18, 2026
e438a4a
docs(format): document the problem slot, step-by-step and drafts
claude Oct 18, 2026
17746fb
fix(app): declare an inline favicon so dev loads stop logging a 404
claude Oct 18, 2026
a674fb2
test(share): drive the share guard through the problem editor
claude Oct 18, 2026
569012c
fix(import-hints): allow one edit for short alias guesses
claude Oct 18, 2026
50c20bb
fix(reader): keep wide card content from widening a phone section
claude Oct 18, 2026
32434aa
test(share): pin payload escaping in the real Reader template shape
claude Oct 18, 2026
9ae61d2
fix(reader): let the coverage matrix scroll in its own box on phones
claude Oct 18, 2026
53566ad
merge: final fixes f1
claude Oct 18, 2026
7e131ab
merge: final fixes f2
claude Oct 18, 2026
f6ee18b
merge: final fixes f3
claude Oct 18, 2026
cfff5ef
release: 0.3.0 — export warns instead of refusing; hashed share docIds
claude Oct 18, 2026
5e01e2e
wip: local changes before testing 0.3.0
YuZh98 Oct 21, 2026
3a5f0ba
merge: local review fixes, keyboard-first Study, zoom and themes into…
claude Oct 21, 2026
ba263b7
refactor: keep one cyrb53 in an import-free hash.ts
claude Oct 21, 2026
326f326
perf: compute the Reader's card keys once per boot
claude Oct 21, 2026
882ca31
fix(problem): warn when a problem answer negates a power
claude Oct 21, 2026
ef77f4b
refactor: copy results through the shared clipboard helper
claude Oct 21, 2026
7093c27
fix(problem): give no credit for an answer the student was shown
claude Oct 21, 2026
f460ada
fix: grade results per question and report practice tries apart
claude Oct 21, 2026
2af470d
perf: inspect the focused card only for keys that act on it
claude Oct 21, 2026
6f19dcb
feat(problem): start each reader on their own practice numbers
claude Oct 21, 2026
0c1f406
fix: keep study keys from reaching cards behind My results
claude Oct 21, 2026
390bd8a
fix(db): skip an unreadable card type row instead of failing hydration
claude Oct 21, 2026
6669905
fix(app): keep a notebook and its progress when its delete fails
claude Oct 21, 2026
2302d64
fix(problem): keep revealed numbers revealed across New numbers
claude Oct 21, 2026
3014ba0
fix(db): make every SQL argument well-formed at the db.ts boundary
claude Oct 21, 2026
a45d6a0
fix: close My results on an Escape that arrives from outside it
claude Oct 21, 2026
202c719
fix(from-ai): ask before Escape discards a typed topic or pasted reply
claude Oct 21, 2026
d2c2b09
fix(from-ai): scroll the discard question into view when Escape asks
claude Oct 21, 2026
516fd8a
merge: PR review fixes for the shared Reader, results and key handling
claude Oct 21, 2026
5154f58
merge: PR review fixes for the problem slot
claude Oct 21, 2026
52b161c
merge: PR review fixes for deletes, card types, From AI and stored st…
claude Oct 21, 2026
e48017e
build(reader): regenerate the share template for the review fixes
claude Oct 21, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
44 changes: 12 additions & 32 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,40 +3,15 @@ name: CI
on:
push:
branches: [main]
paths:
- 'v2/**'
- '.github/workflows/ci.yml'
pull_request:
paths:
- 'v2/**'
- '.github/workflows/ci.yml'

jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm

- name: Install dependencies
run: npm ci

- name: Build bundle
run: npm run build

- name: Lint
run: npm run lint

- name: Check formatting
run: npm run format:check

- name: Verify committed bundle is up to date
run: git diff --exit-code -- index.html

- name: Install Playwright browser
run: npx playwright install --with-deps chromium

- name: Test
run: npm test

check-v2:
runs-on: ubuntu-latest
defaults:
Expand All @@ -47,7 +22,8 @@ jobs:

- uses: actions/setup-node@v4
with:
node-version: 20
# 22: db-sql.test.ts runs the real SQL through node:sqlite (skipped on older Node).
node-version: 22
cache: npm
cache-dependency-path: v2/package-lock.json

Expand All @@ -62,3 +38,7 @@ jobs:

- name: Build
run: npm run build

- name: Verify committed Reader template is up to date
# Shared .html files are built from this generated bundle; a stale one ships old behavior.
run: npm run build:reader && git diff --exit-code -- src/lib/generated/reader-template.ts
72 changes: 72 additions & 0 deletions .github/workflows/v1.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
name: CI v1

on:
push:
branches: [main]
paths:
- 'src/**'
- 'scripts/**'
- 'tests/**'
- 'index.html'
- 'index.template.html'
- 'package.json'
- 'package-lock.json'
- 'playwright.config.mjs'
- 'eslint.config.mjs'
- '.github/workflows/v1.yml'
pull_request:
paths:
- 'src/**'
- 'scripts/**'
- 'tests/**'
- 'index.html'
- 'index.template.html'
- 'package.json'
- 'package-lock.json'
- 'playwright.config.mjs'
- 'eslint.config.mjs'
- '.github/workflows/v1.yml'

jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm

- name: Install dependencies
run: npm ci

- name: Build bundle
run: npm run build

- name: Lint
run: npm run lint

- name: Check formatting
run: npm run format:check

- name: Verify committed bundle is up to date
run: git diff --exit-code -- index.html

- name: Cache Playwright browser
id: playwright-cache
uses: actions/cache@v4
with:
path: ~/.cache/ms-playwright
key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

- name: Install Playwright browser
if: steps.playwright-cache.outputs.cache-hit != 'true'
run: npx playwright install --with-deps chromium

- name: Install Playwright system deps
if: steps.playwright-cache.outputs.cache-hit == 'true'
run: npx playwright install-deps chromium

- name: Test
run: npm test
81 changes: 79 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,83 @@
Notable changes, following [Keep a Changelog](https://keepachangelog.com/). The notebook JSON
interchange format is versioned separately and migrated on import.

## [0.3.0] — 2026-10-21

The living handout: notebooks an LLM can draft, a teacher can trust, and a student can keep — plus a
keyboard-first Study, zoom, the Cyberpunk theme and a much larger test suite.

- **Shared files remember progress.** A shared Reader `.html` keeps each reader's answers, ticks,
practice streaks and notes in that browser, keyed by card content so an author's later fixes
keep everyone else's progress. "Reset my progress" starts over.
- **Results for the teacher.** "My results" in the Reader summarizes progress per section and
graded answers; copy it or download it as JSON. Nothing leaves the device otherwise.
- **`problem` slot (12th).** Randomized numeric practice: params drawn on a step grid each attempt,
the typed answer checked against an expression with a tolerance, "New numbers", a worked
explanation, done after `need` correct answers. Strict answer parsing; mobile keypad friendly.
- **Guided card types.** Guided Explore (predict → explore with sliders and a chart → explain),
Worked Example (steps with self-explanation fading into practice) and Practice Set. Existing
installs receive new built-ins once through a preferences ledger; deleted ones stay deleted. Predictions with no answer key
are never marked wrong.
- **Step-by-step** slot effect in the Factory: hide a slot until the earlier tasks on its card
are done.
- **New notebook From AI.** A complete prompt for any chat AI (format, slot catalog, expression
grammar, card-scope rule, pedagogy); paste the reply, see problems with where / what / how to
fix and a copyable fix request, then create. Cards arrive as **drafts** to review; Share warns
while drafts remain.
- **Published format.** JSON Schema 2020-12 (`v2/src/lib/schema/notebook.schema.json`) and
[`docs/FORMAT.md`](docs/FORMAT.md). Rejected imports show a readable report instead of a toast.
- **Durability.** Saves are serialized and atomic (one batch per save), flushed on blur, window
close and Cmd+Q, and never written before startup loading finishes. Fixed: edits lost when
switching notebooks, the demo notebook overwriting a stored one at startup, interleaved saves
failing silently, card widths snapping back to full width after a relaunch, section resets
coming back after a restart.
- **Version history.** Automatic snapshots (at most every 10 minutes, only on change), "Save
version now", and Restore (undoable). SQLite migration v6.
- **Shared files on phones and offline.** Under 760 px the Reader starts with its panel collapsed
and cards go full width; the file makes no third-party request (the web-font import is
stripped at build, and the build fails on any external reference); a damaged file shows a
readable message instead of a blank page; the embedded payload escapes every `<`.
- **Safer sharing.** Share is refused while the notebook fails validation (the report lists
why), so students never get a broken file; Export still writes the backup and then lists what
would stop it re-importing. Progress keys are a hash of a per-install id and the notebook id,
so two authors' files never share students' progress. Imported text is made well-formed
before it reaches SQLite.
- **Examples.** `docs/examples/practice-lesson.json` (percent change) shows every new piece.
- CI runs the v2 job on Node 22 (real-SQLite tests) and fails on a stale Reader template.
- **Keyboard-first Study** — a whole study session runs from the keyboard: `j`/`k` (or the arrow
keys) move a focus ring from card to card, space or `f` flips, `1`-`9` pick an answer option,
`Enter` submits, `x` ticks the next checklist item, and `Escape` clears the focus. `?` opens a
shortcut overlay and Study carries a one-line hint under the notebook. The same bindings work
in a shared Reader file.
- **Cyberpunk (dark green) theme** — phosphor green on near-black with a fixed grid, scanlines,
neon card glow, hover lift, and mono uppercase headers. Bold, italic, inline code and
strikethrough take accent colors in Study text under this theme.
- **Syntax-highlighted code slots** — Python and JavaScript keywords, strings, numbers,
comments and callables get distinct colors via a dependency-free tokenizer; other languages
render plain.
- **Zoom** — `Cmd/Ctrl` `+`, `-`, `0` scale the whole app between 50% and 200%.
- **Three more builtin card types** — Cheatsheet, Iron Butterfly (a payoff explorer whose
breakevens and max profit and loss derive from three sliders), and Code Card, each with
accent varieties.
- **Examples** — `docs/examples/grand-tour.json` exercises every slot type in one tutorial;
`docs/examples/quant-terminal.json` rebuilds the quant-prep-terminal cockpit with chapter
dividers, tagged flashcards, cheatsheets, a lab section, and per-section service bars.
- **Styled DMG** — the disk image opens as a proper installer window with a
drag-to-Applications layout; `docs/install-macos.md` documents the build.
- **Simulation test tier** — seeded generative suites cover variable-graph resolution,
interchange round-trips, progress semantics, and expression evaluation.
- **Card type binding survives export** — a card stamped from a Factory type now carries its
`typeId` through JSON export and import, so the coverage matrix keeps its product dimension on
a round trip. A recipient without that type reads the card as untyped.
- **Design tokens** — spacing, type, radius and motion tokens with a written governance rule;
components consolidated onto them with zero visual change.
- **Fixed: Edit-in-Factory on typed cards** — the 🏭 action on a card stamped from a card type
silently did nothing instead of forking the type into a Factory bench.
- **Hardened test suite** — the SQLite persistence layer, every example notebook, the Iron
Butterfly payoff math, undo restoration of card types and Factory benches, the shortcut
overlay, Reader authoring after Remix, and every slot component are now under test; the
suite is 2718 tests across 204 files, plus real-SQLite tests of every migration.

## [0.2.0] — 2026-07-23

NoteBuilder becomes a native macOS desktop app (`v2/`): Svelte 5 + TypeScript + Tauri 2, backed by
Expand All @@ -12,8 +89,8 @@ SQLite. Rebuilds the full prototype experience on a typed engine and moves it fo
card types, stamp independent copies into notebooks.
- **11 slots** — text, list, code, table, image, choice, slider, text input, compute, chart,
progress — composed on a 12-column grid with per-slot resize and fusing.
- **Card-scoped variables** with a topologically sorted dependency graph; cycles and missing
writers are rejected at import.
- **Card-scoped variables** with a topologically sorted dependency graph; cycles are rejected
at import and missing writers load with a warning.
- **Hard Edit/Study separation** (`Cmd+Enter`); Study is the live, interactive render.
- **Three state layers**: document (persists + exports), reader state (persists locally, never
exports), session (transient).
Expand Down
83 changes: 83 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# Contributor Covenant Code of Conduct

## Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

## Our Standards

Examples of behavior that contributes to a positive environment for our community include:

* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
* Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

* The use of sexualized language or imagery, and sexual attention or advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting

## Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

## Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at the maintainer's GitHub contact (@YuZh98, https://github.com/YuZh98). All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

## Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

### 1. Correction

**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

### 2. Warning

**Community Impact**: A violation through a single incident or series of actions.

**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

### 3. Temporary Ban

**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.

**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

### 4. Permanent Ban

**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

**Consequence**: A permanent ban from any sort of public interaction within the community.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].

Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].

For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].

[homepage]: https://www.contributor-covenant.org
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
[Mozilla CoC]: https://github.com/mozilla/diversity
[FAQ]: https://www.contributor-covenant.org/faq
[translations]: https://www.contributor-covenant.org/translations
24 changes: 19 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,16 @@
# Contributing to NoteBuilder

## Scope

NoteBuilder is one repo, two apps: the **v1 prototype** at the root (frozen, bug fixes only) and the
**v2 product** in `v2/` (Svelte 5 + TypeScript + Tauri 2, active development).

In scope: v2 app quality, interchange/Reader fidelity, tests, and docs accuracy.

Out of scope: anything that adds a network call, telemetry, or an account system (NoteBuilder is
local-first and stays that way); changes to the v1 root beyond bug fixes; features not grounded in an
open issue.

Thanks for helping. Active development happens in **`v2/`** (Svelte 5 + TypeScript + Tauri 2); the
repository root is the legacy single-file prototype, kept building but not evolving.

Expand All @@ -8,7 +19,7 @@ repository root is the legacy single-file prototype, kept building but not evolv
```bash
cd v2
npm install
npm run dev # browser dev server (persistence no-ops; demo notebook loads)
npm run dev # browser dev server (persistence no-ops; demo notebook loads); Node 22+
npm run tauri dev # the real desktop app — needs Rust + Xcode CLT
```

Expand All @@ -18,21 +29,24 @@ Gates — keep all green before and after every change:
npm test # Vitest unit suite
npm run check # svelte-check, TypeScript strict
npm run build # Vite production build
npm run build:reader # only when the Reader render path changes — commit the regenerated template
npm run build:reader # when the Reader render path changes — commit the regenerated template (CI fails on a stale one)
```

## The shape of v2

- Architecture map: Part B of [`docs/CODE-MAP.md`](docs/CODE-MAP.md). Product spec:
[`docs/spec/v2-spec.md`](docs/spec/v2-spec.md).
- Architecture map: Part B of [`docs/CODE-MAP.md`](docs/CODE-MAP.md).
- **Invariants** (don't break): variables are card-scoped, never cross a card boundary; three state
layers (document persists + exports · reader state persists locally, never exports · session is
transient); slot structure is sealed outside the Factory; every drag rides the one pointer engine
in `v2/src/lib/drag/` — no native HTML5 drag; no `eval` on user content, escape-first before any
in `v2/src/lib/drag/` — no native HTML5 drag outside the Factory inventory chips; no `eval` on
user content, escape-first before any
`{@html}`; every document edit is undoable.
- **Migrations always.** A change to the SQLite shape ships a migration in
`v2/src-tauri/src/lib.rs`; a change to the JSON interchange shape bumps its schema version and
ships an import migration. Old saves and old exports must still load.
- **The interchange format is published.** A change to it updates `v2/src/lib/schema/notebook.schema.json`,
`v2/src/lib/slot-catalog.ts` (for a new slot type) and `docs/FORMAT.md`; `schema-sync.test.ts` and
`ai-prompt.test.ts` name whatever is missing.
- **Behavior changes are test-driven** — add a failing test, then make it pass. Verify UI and
interaction changes by running the app, not by reading the diff.

Expand Down
Loading
Loading