Contributing

You need Node.js 22 or newer. No accounts, keys or services are required.

git clone https://github.com/yakshjethva/jvm-inside-out.git
cd jvm-inside-out
npm ci
npm run dev

Before opening a pull request run npm run check (type check, lint, unit tests and a production build). Browser tests run with npm run test:e2e.

• src/content/jvm/components/*.ts: one entry per anatomy component (explanations, examples, misconceptions, sources).
• src/content/jvm/relationships.ts and scenarios.ts: connectors and execution walkthroughs.
• src/glossary/terms.ts: glossary entries. Link a term from any text with [[term-id]] or [[term-id|label]].
• src/data/references.ts: the source registry. Cite a source by id; the type check fails if it does not exist.
• src/modules/jvm/layout.ts: coordinates and connector routes, kept apart from the content.
• src/content/jvm/teaching.ts: the teaching layer of the twelve core concepts (developer explanation, analogy, demo and check question).
• src/content/lesson/firstRun.ts, src/modules/lesson/ and src/simulators/: the Start here lesson, its interactive exhibits and the pure models behind them.

A component entry looks like this (types are checked, and integrity tests check every link and citation):

{
  id: 'operand-stack',
  name: 'Operand stack',
  parent: 'stack-frame',
  provenance: 'spec',            // 'spec' | 'hotspot' | 'platform'
  scope: 'per-thread',
  summary: 'A per-frame LIFO scratch stack ...',
  simple: 'The JVM is a stack machine ...',  // no programming knowledge needed
  // developer: '...',              optional: code, APIs, what you can observe
  deep: 'JVMS §2.6.2: ... [[verification|The verifier]] proves ...',
  purpose: '...',
  internals: ['...'],
  inputs: ['...'],
  outputs: ['...'],
  practice: '...',
  misconceptions: [{ myth: '...', truth: '...' }],
  references: [{ source: 'jvms-2.6.2' }],
}

• Write each explanation at three levels that describe the same machine: Simple (no programming knowledge, one new term at a time), Developer (code and what you can observe) and Deep dive (specification sections, HotSpot mechanisms, bytecode and flags). Simple is short, never false.
• An analogy maps each part of its picture to the real concept and says where the picture stops being accurate. It opens a door; it never replaces the explanation.
• Every interactive teaches cause and effect: the learner acts, the visual changes, and a caption says what changed and why. It can be stepped, paused and replayed.
• Disclose depth, never delete it: technical detail goes behind “Explore the technical details” rather than into the default view.

A core concept’s teaching entry has this shape:

heap: {
  developer: 'Every `new`, and every array, allocates in the heap. ...',
  analogy: {
    picture: 'A big shared warehouse. Each object is a box on a shelf, ...',
    mapping: [
      { picture: 'The warehouse', real: 'The heap' },
      { picture: 'A claim ticket', real: 'A reference, held by a variable or a field' },
      // ...
    ],
    limits: 'A ticket is not a shelf number you can do arithmetic with: ...',
  },
  demo: 'memory',                   // a lesson exhibit, shown under "See it working"
  check: { id: 'check-heap', prompt: '...', options: [/* one correct */] },
}

• Is the claim defined by the specification, or is it HotSpot behaviour? Say which, and set the provenance.
• Name the Java version for anything implementation-specific.
• Never hand-write bytecode or log output. Produce it with a real JDK and record the version in verifiedWith.
• Cite a primary source: JVMS, JLS, API docs, a JEP or the OpenJDK source at a release tag.
• If a diagram or simulation simplifies something, add an accuracy note that says what.

• Every visual must explain a real technical concept. No decorative diagrams or stock images.
• Colour always comes with a second cue (line style, glyph or text): blue is control flow, purple runtime components, green success, orange warnings, grey inactive.
• Every interactive element must work with a keyboard and have an accessible name.
• No links to pages that do not exist yet.