{"_id":"@1984vc/cap-table","_rev":"5-dac97efdc5b5be0b8018104bc6116d5c","name":"@1984vc/cap-table","dist-tags":{"latest":"0.4.0"},"versions":{"0.1.0":{"name":"@1984vc/cap-table","version":"0.1.0","license":"MIT","_id":"@1984vc/cap-table@0.1.0","maintainers":[{"name":"markpercival","email":"m@mdp.im"}],"dist":{"shasum":"0678b8505cc92f8e24a05d8ba41e36c751beb3a4","tarball":"https://registry.npmjs.org/@1984vc/cap-table/-/cap-table-0.1.0.tgz","fileCount":8,"integrity":"sha512-MQclGfVwfyb8LzWPCq+ikKROQh2YqUQSgLfx6hh8LZu6LS5ykWYkzgxv7/gIcil4B6Blh8VOJkPOkMUXEhavOQ==","signatures":[{"sig":"MEQCIFuxhXlmoPHh5aKZu7vv0WIb2GAG7ICSbiNSujw2eQPDAiBLW6UFcnpdKwhzNjPYITIDevoXDHfBObABf1wYkBoKqg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":144106},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"04fdae5a00c807b8b775e774c5bfaa18e50d294c","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","test:watch":"vitest"},"_npmUser":{"name":"markpercival","email":"m@mdp.im"},"_npmVersion":"11.11.0","description":"Cap table calculations for startup equity modeling","directories":{},"_nodeVersion":"25.8.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^3.0.0","typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/cap-table_0.1.0_1778014188105_0.44799371903041796","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@1984vc/cap-table","version":"0.2.0","license":"MIT","_id":"@1984vc/cap-table@0.2.0","maintainers":[{"name":"markpercival","email":"m@mdp.im"}],"bin":{"cap-table":"dist/cli.js"},"dist":{"shasum":"a1a432dcd6f6a2bea76ab0c45b361a623b1e12e0","tarball":"https://registry.npmjs.org/@1984vc/cap-table/-/cap-table-0.2.0.tgz","fileCount":11,"integrity":"sha512-CMtJAMoZ1jCQm/uHUcSH4+5m/YsXNNzCWrcgPLg5Xjr4urJu/M03SWSu4XMiJlw4S1E0f4HAFph9W6CHSVYigw==","signatures":[{"sig":"MEUCIQCn1FSJmQYh1iwsoqo04bkXKNGae+2p1iGEnhj5siyk2wIgSuCq4F+on+XmMwCfSsSxs/erhUMjXadj2cZFH0oFaHE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":228592},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"25806ccd0a289899d7d8b8304d891e97134206ce","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","test:watch":"vitest"},"_npmUser":{"name":"markpercival","email":"m@mdp.im"},"_npmVersion":"11.12.1","description":"Cap table calculations for startup equity modeling","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^26.1.1"},"_npmOperationalInternal":{"tmp":"tmp/cap-table_0.2.0_1784227693943_0.9503453834923892","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@1984vc/cap-table","version":"0.2.1","license":"MIT","_id":"@1984vc/cap-table@0.2.1","maintainers":[{"name":"markpercival","email":"m@mdp.im"}],"bin":{"cap-table":"dist/cli.js"},"dist":{"shasum":"f562a418ccf53148705ad3f9292f846ec3876acb","tarball":"https://registry.npmjs.org/@1984vc/cap-table/-/cap-table-0.2.1.tgz","fileCount":11,"integrity":"sha512-1jOGiAtZpRknLWMuq1EtBuedjCY3Ed1nvWEix5PWLnY1Duw2QvdylFQOhowHg3NJbZZRMAwYV1R30ZF5nAa/0w==","signatures":[{"sig":"MEUCIQCrjcTQhWN1O79FVfpJIReks88iubYyONn6bCYh7PA3+wIgPsqqE+S+08t/CE5HV4Vippu8uF5yE0Ff9yhOyF++7c0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":229618},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"7fa8e1cda1b9613d248369b6827057dfbdc3a2a8","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","test:watch":"vitest"},"_npmUser":{"name":"markpercival","email":"m@mdp.im"},"_npmVersion":"11.12.1","description":"Cap table calculations for startup equity modeling","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^26.1.1"},"_npmOperationalInternal":{"tmp":"tmp/cap-table_0.2.1_1784231657944_0.509585085041528","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@1984vc/cap-table","version":"0.3.0","license":"MIT","_id":"@1984vc/cap-table@0.3.0","maintainers":[{"name":"markpercival","email":"m@mdp.im"}],"bin":{"cap-table":"dist/cli.js"},"dist":{"shasum":"22d64b6fb4f0c50faf65d95c0d353b1023c681fb","tarball":"https://registry.npmjs.org/@1984vc/cap-table/-/cap-table-0.3.0.tgz","fileCount":11,"integrity":"sha512-tkRm4oGVO2V2OrRDP8UjxK6Hvut5zELWxLevT8nKmd9qJOctkCGXvfwAaG93CiwKmEEW1e8v2NboYiC5+Yy6PQ==","signatures":[{"sig":"MEUCIQC+jpCR+mGK4rxvM7PPEoouJPUw5M6BLE5Qvi6AJEKyMQIgdLZ7VLHW09jjIBqZEvBww34uZDi3hdAlrfM/TVYc5Vg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":315583},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"c5a49682b60213e0b2e88f7cb08be89e8d1cca91","scripts":{"dev":"tsup --watch","test":"pnpm build && vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"markpercival","email":"m@mdp.im"},"_npmVersion":"11.9.0","description":"Cap table calculations for startup equity modeling","directories":{},"_nodeVersion":"24.14.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^26.1.1"},"_npmOperationalInternal":{"tmp":"tmp/cap-table_0.3.0_1785356997027_0.3789997042580193","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@1984vc/cap-table","version":"0.4.0","description":"Cap table calculations for startup equity modeling","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","bin":{"cap-table":"dist/cli.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"pnpm build && vitest run","typecheck":"tsc --noEmit","test:watch":"vitest"},"engines":{"node":">=18"},"license":"MIT","devDependencies":{"@types/node":"^26.1.1","tsup":"^8.0.0","typescript":"^5.7.0","vitest":"^3.0.0"},"gitHead":"6f188de0d25867c1213373cce7764368d68a1ead","_id":"@1984vc/cap-table@0.4.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-kkP/P5m+5qXVEqT1XMgzvhq6a46ismExJh3xC949Q8z/IYKNvnI1EV8bU7p8IlGzAxogz8S4Kio6tdlwdFc03g==","shasum":"0f548309721e004b5fb9d39d79b6bcdd47763735","tarball":"https://registry.npmjs.org/@1984vc/cap-table/-/cap-table-0.4.0.tgz","fileCount":11,"unpackedSize":333242,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFYPu5XXvmKA6r4TYhIyN4XppMz6LxP/jU8G++QJq3//AiEAvxGG5RtMRwLFSRF669o3mUpdAwLmyDCLTdyHlBWAn2c="}]},"_npmUser":{"name":"markpercival","email":"m@mdp.im"},"directories":{},"maintainers":[{"name":"markpercival","email":"m@mdp.im"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cap-table_0.4.0_1787184204615_0.013769274828384859"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-05T20:49:48.043Z","modified":"2026-08-20T00:03:24.925Z","0.1.0":"2026-05-05T20:49:48.260Z","0.2.0":"2026-07-16T18:48:14.131Z","0.2.1":"2026-07-16T19:54:18.097Z","0.3.0":"2026-07-29T20:29:57.179Z","0.4.0":"2026-08-20T00:03:24.762Z"},"license":"MIT","description":"Cap table calculations for startup equity modeling","maintainers":[{"name":"markpercival","email":"m@mdp.im"}],"readme":"# @1984vc/cap-table\n\nModel your cap table when the math stops being obvious.\n\nA 50/50 founder split is easy. The hard part starts when you add issued\noptions, an unused pool, several SAFEs with different caps, YC terms, an MFN\nside letter, a priced round, and an investor-requested option-pool refresh.\nThose terms interact recursively, and small PPS or share-rounding differences\ncan change the final ownership.\n\n`@1984vc/cap-table` gives an AI agent or application a deterministic,\nwell-tested calculation engine for that work. It powers the free\n[1984 Ventures Cap Table Worksheet](https://startup-finance.1984.vc/).\n\n## Use it with an AI coding agent\n\n### Install the cap-table skill\n\nInstall the skill so a compatible agent knows what to ask, which command to\nrun, and how to explain the result:\n\n```bash\nnpx skills add 1984vc/cap-table\n```\n\nThen ask:\n\n```text\nHelp me model my cap table. I have founders, an existing option pool,\nseveral SAFEs, and proposed terms for my next priced round.\n```\n\nThe skill uses the hosted\n[Cap Table 101 Markdown](https://1984.vc/docs/founders-handbook/cap-table-101.md)\nfor founder-facing concepts and uses this package for the actual math.\n\n### Paste this into a CLI agent\n\nYou can also point Codex, Claude Code, Cursor, or another command-line coding\nagent directly at the project:\n\n```text\nUse https://github.com/1984vc/cap-table to help me model my cap table.\nAsk me for my current shareholders and share counts, issued and unused\noptions, every SAFE in chronological order, and the proposed priced-round\nand option-pool terms. Use the package's npx CLI for the calculations,\nthen explain the ownership before and after the financing.\n```\n\nThe agent can run the calculator without cloning or installing the library:\n\n```bash\nnpx @1984vc/cap-table priced-round ./scenario.json\n```\n\n## The kind of scenario this tool is for\n\nConsider a company with:\n\n- Two founders holding 4,500,000 shares each.\n- 250,000 issued employee options.\n- 750,000 still available in the option pool.\n- Five outstanding SAFEs:\n  - YC 7% for $125,000.\n  - YC MFN for $375,000.\n  - $750,000 at a $10M post-money cap.\n  - $475,000 at a $10M post-money cap.\n  - $500,000 at a $13M post-money cap.\n- A proposed $4M priced round at a $25M pre-money valuation.\n- A request to refresh the available option pool to 10% after the financing.\n\nBefore the SAFEs and priced round, the founders each own 45% of the fully\ndiluted opening cap table. What they own afterward is not a one-line dilution\ncalculation: the SAFE shares, round PPS, Series shares, and pool refresh all\ndepend on one another.\n\nRun the complete scenario:\n\n```bash\nnpx @1984vc/cap-table priced-round '{\n  \"preMoneyValuation\": 25000000,\n  \"common\": [\n    { \"name\": \"Founder A\", \"shares\": 4500000 },\n    { \"name\": \"Founder B\", \"shares\": 4500000 },\n    { \"name\": \"Issued Options\", \"shares\": 250000 },\n    {\n      \"name\": \"Available Option Pool\",\n      \"shares\": 750000,\n      \"commonType\": \"unusedOptions\"\n    }\n  ],\n  \"safes\": [\n    {\n      \"name\": \"YC 7%\",\n      \"investment\": 125000,\n      \"conversionType\": \"yc7p\"\n    },\n    {\n      \"name\": \"YC MFN\",\n      \"investment\": 375000,\n      \"conversionType\": \"post\",\n      \"sideLetters\": [\"mfn\"]\n    },\n    {\n      \"name\": \"1984 Ventures\",\n      \"investment\": 750000,\n      \"cap\": 10000000,\n      \"conversionType\": \"post\"\n    },\n    {\n      \"name\": \"Benchmark\",\n      \"investment\": 475000,\n      \"cap\": 10000000,\n      \"conversionType\": \"post\"\n    },\n    {\n      \"name\": \"Follow-on SAFE\",\n      \"investment\": 500000,\n      \"cap\": 13000000,\n      \"conversionType\": \"post\"\n    }\n  ],\n  \"seriesInvestors\": [\n    { \"name\": \"Series A Lead\", \"investment\": 4000000 }\n  ],\n  \"targetOptionsPct\": 0.10\n}'\n```\n\nThe reconciled result is:\n\n| Holder | Final shares | Final ownership |\n|---|---:|---:|\n| Founder A | 4,500,000 | 26.54% |\n| Founder B | 4,500,000 | 26.54% |\n| Issued Options | 250,000 | 1.47% |\n| YC 7% | 956,884 | 5.64% |\n| YC MFN | 512,610 | 3.02% |\n| 1984 Ventures | 1,025,220 | 6.05% |\n| Benchmark | 649,306 | 3.83% |\n| Follow-on SAFE | 525,756 | 3.10% |\n| Series A Lead | 2,338,415 | 13.79% |\n| Available Option Pool | 1,695,354 | 10.00% |\n| **Total** | **16,953,545** | **100.00%** |\n\nThe useful answers are not just the final percentages:\n\n- The round PPS is `$1.71056` after solving all conversions and the pool refresh.\n- The YC 7% SAFE receives exactly 7% immediately before the new Series shares\n  and pool increase dilute it to 5.64% post-financing.\n- The YC MFN elects the later $10M post-money SAFE package.\n- Refreshing the existing 750,000-share pool to 10% requires 945,354 additional\n  options.\n- The two founders move from 90% combined ownership to 53.09%.\n- The final legal share counts reconcile exactly to 16,953,545 shares.\n\nThis is the division of labor that works well with AI: let the agent gather the\nfacts, explore scenarios, and explain the tradeoffs; let a tested financial\nmodel perform the recursive calculation and legal rounding.\n\n## What the agent will need from you\n\nFor the best result, have these inputs available:\n\n1. Every current holder and their issued shares.\n2. Issued employee options and the unused option pool as separate amounts.\n3. Every SAFE in chronological order, including investment, cap, discount,\n   conversion type, and side letters.\n4. The proposed pre-money valuation and each new investor's check size.\n5. The target post-financing option-pool percentage.\n\nSAFE order matters for MFN elections. If a term is unknown, say so—the\n`estimated-pre-round` command marks assumptions and unavailable calculations\ninstead of presenting them as exact.\n\n## Choose the right command\n\n| Command | Use it when |\n|---|---|\n| `existing` | You want a clean view of current issued ownership and the available pool |\n| `estimated-pre-round` | SAFEs are outstanding but the priced-round terms are not known |\n| `pre-round` | The next-round terms are known and you want ownership after SAFE conversion but before new money |\n| `priced-round` | You want the complete post-financing cap table, including Series shares and the refreshed pool |\n\nPass input as inline JSON, through stdin, or from a file:\n\n```bash\nnpx @1984vc/cap-table priced-round ./scenario.json\ncat scenario.json | npx @1984vc/cap-table priced-round\nnpx @1984vc/cap-table --help\n```\n\n## Understand the output\n\nA priced-round calculation returns:\n\n```json\n{\n  \"conversion\": {\n    \"pps\": 1.71056,\n    \"safeConversions\": [],\n    \"seriesInvestorShares\": [],\n    \"additionalOptions\": 945354,\n    \"totalShares\": 16953545\n  },\n  \"capTable\": {\n    \"common\": [],\n    \"safes\": [],\n    \"series\": [],\n    \"optionsPool\": {},\n    \"total\": {}\n  }\n}\n```\n\n- `conversion` records the PPS, controlling SAFE terms, investor allocations,\n  pool increase, and exact reconciled share totals.\n- `common` contains founders, employees, and other issued opening shares.\n- `safes` contains each SAFE's effective terms and converted shares.\n- `series` contains the investors purchasing shares in this financing.\n- `optionsPool` is the unissued pool reserved for future grants.\n- `total` reconciles all rows to 100%.\n\nShare counts are floored and PPS is rounded up to five decimal places by\ndefault, matching common legal spreadsheet conventions. Invalid or unsupported\ntransactions fail with a stable error code instead of returning a plausible but\nincorrect cap table.\n\n## Use the library directly\n\nApplications can call the same engine from TypeScript:\n\n```bash\nnpm install @1984vc/cap-table\n```\n\n```typescript\nimport {\n  buildPricedRoundCapTable,\n  fitConversion,\n} from \"@1984vc/cap-table\";\n\nconst conversion = fitConversion(\n  preMoneyValuation,\n  issuedShares,\n  safes,\n  unusedOptions,\n  targetOptionsPct,\n  seriesInvestments,\n);\n\nconst capTable = buildPricedRoundCapTable(conversion, stakeholders);\n```\n\n| Function | Purpose |\n|---|---|\n| `buildExistingShareholderCapTable` | Calculate the current ownership snapshot |\n| `buildEstimatedPreRoundCapTable` | Estimate SAFE ownership without priced-round terms |\n| `fitConversion` | Solve SAFE conversions, PPS, investor shares, and the pool refresh |\n| `buildPreRoundCapTable` | Build exact ownership immediately before new money |\n| `buildPricedRoundCapTable` | Build the fully diluted post-financing cap table |\n\nAll public inputs are validated. Failures throw `CalculationError` with\n`INVALID_INPUT`, `UNSUPPORTED_TERMS`, `CONFLICTING_TRANSACTION_DATA`, or\n`UNRECONCILED_ROUNDING`.\n\n## Model boundaries\n\n- One calculation models the current cap table plus one upcoming financing\n  event. Use its final shares as the opening snapshot for a later round.\n- Pro-rata participation is not yet represented and is rejected rather than\n  silently omitted.\n- The package models ownership and dilution, not liquidation preferences,\n  waterfall proceeds, taxes, or legal compliance.\n\n## Development\n\n```bash\npnpm install\npnpm typecheck\npnpm test\n```\n\n## Disclaimer\n\nThis project is an educational modeling tool, not legal, tax, or investment\nadvice. Work with qualified counsel when issuing securities or completing a\nfinancing.\n\n## License\n\nMIT — [1984 Ventures](https://1984.vc/)\n","readmeFilename":"README.md"}