product-doc 0.0.0-stage → 0.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (482) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +575 -2
  3. package/bin.js +6 -0
  4. package/guide/previews.md +64 -0
  5. package/guide/ui.md +13 -0
  6. package/guide.md +254 -0
  7. package/lib/annotations.d.ts +44 -0
  8. package/lib/annotations.js +65 -0
  9. package/lib/changes.d.ts +100 -0
  10. package/lib/changes.js +116 -0
  11. package/lib/cli.d.ts +1 -0
  12. package/lib/cli.js +304 -0
  13. package/lib/codeNotes.d.ts +38 -0
  14. package/lib/codeNotes.js +113 -0
  15. package/lib/definitions.d.ts +23 -0
  16. package/lib/definitions.js +298 -0
  17. package/lib/diagramAnnotations.d.ts +7 -0
  18. package/lib/diagramAnnotations.js +27 -0
  19. package/lib/diffmapConfig.d.ts +41 -0
  20. package/lib/diffmapConfig.js +71 -0
  21. package/lib/errors.d.ts +44 -0
  22. package/lib/errors.js +71 -0
  23. package/lib/extractDocument.d.ts +3 -0
  24. package/lib/extractDocument.js +22 -0
  25. package/lib/gist/route.d.ts +26 -0
  26. package/lib/gist/route.js +124 -0
  27. package/lib/git.d.ts +38 -0
  28. package/lib/git.js +509 -0
  29. package/lib/github/route.d.ts +29 -0
  30. package/lib/github/route.js +137 -0
  31. package/lib/index.d.ts +10 -0
  32. package/lib/index.js +7 -0
  33. package/lib/invokeCwd.d.ts +1 -0
  34. package/lib/invokeCwd.js +9 -0
  35. package/lib/media.d.ts +5 -0
  36. package/lib/media.js +9 -0
  37. package/lib/mermaid.d.ts +6 -0
  38. package/lib/mermaid.js +20 -0
  39. package/lib/mermaidTheme.d.ts +17 -0
  40. package/lib/mermaidTheme.js +28 -0
  41. package/lib/packageVersion.d.ts +1 -0
  42. package/lib/packageVersion.js +3 -0
  43. package/lib/parseFence.d.ts +106 -0
  44. package/lib/parseFence.js +199 -0
  45. package/lib/parseViewer.d.ts +74 -0
  46. package/lib/parseViewer.js +505 -0
  47. package/lib/preview/PreviewRoute.d.ts +20 -0
  48. package/lib/preview/PreviewRoute.js +279 -0
  49. package/lib/preview/index.d.ts +3 -0
  50. package/lib/preview/index.js +2 -0
  51. package/lib/preview/protocol.d.ts +85 -0
  52. package/lib/preview/protocol.js +114 -0
  53. package/lib/readDiffmapConfig.d.ts +12 -0
  54. package/lib/readDiffmapConfig.js +25 -0
  55. package/lib/readSpec.d.ts +25 -0
  56. package/lib/readSpec.js +62 -0
  57. package/lib/registry.d.ts +11 -0
  58. package/lib/registry.js +82 -0
  59. package/lib/serve.d.ts +72 -0
  60. package/lib/serve.js +790 -0
  61. package/lib/services.d.ts +107 -0
  62. package/lib/services.js +310 -0
  63. package/lib/share.d.ts +15 -0
  64. package/lib/share.js +157 -0
  65. package/lib/spec.d.ts +39 -0
  66. package/lib/spec.js +95 -0
  67. package/lib/telemetry.d.ts +6 -0
  68. package/lib/telemetry.js +109 -0
  69. package/lib/update.d.ts +43 -0
  70. package/lib/update.js +237 -0
  71. package/package.json +96 -4
  72. package/viewer-dist/assets/abap-CLvhMVsD.js +1 -0
  73. package/viewer-dist/assets/actionscript-3-Cs6JJXT5.js +1 -0
  74. package/viewer-dist/assets/ada-X3Y2mlq2.js +1 -0
  75. package/viewer-dist/assets/ahk-DwADkxyd.js +1 -0
  76. package/viewer-dist/assets/ahk2-_6rzW9BS.js +1 -0
  77. package/viewer-dist/assets/andromeeda-BJLMrMlp.js +1 -0
  78. package/viewer-dist/assets/andromeeda-vGVdxbeo.js +1 -0
  79. package/viewer-dist/assets/angular-html-C4LeXCe-.js +1 -0
  80. package/viewer-dist/assets/angular-ts-CRxW7p1W.js +1 -0
  81. package/viewer-dist/assets/apache-U0d_L8uA.js +1 -0
  82. package/viewer-dist/assets/apex-KFGFyKwG.js +1 -0
  83. package/viewer-dist/assets/apl-D60kkz--.js +1 -0
  84. package/viewer-dist/assets/applescript-CCn79oCD.js +1 -0
  85. package/viewer-dist/assets/ara-4CJ0cIlV.js +1 -0
  86. package/viewer-dist/assets/asciidoc-SCjQUq34.js +1 -0
  87. package/viewer-dist/assets/asm-Cmm7eHzH.js +1 -0
  88. package/viewer-dist/assets/astro-3Zgg9XqN.js +1 -0
  89. package/viewer-dist/assets/aurora-x-BCChoRpm.js +1 -0
  90. package/viewer-dist/assets/aurora-x-CDeNXAV0.js +1 -0
  91. package/viewer-dist/assets/awk-BWXHIvNe.js +1 -0
  92. package/viewer-dist/assets/ayu-dark-DluEY0Gj.js +1 -0
  93. package/viewer-dist/assets/ayu-dark-DzFZPuMV.js +1 -0
  94. package/viewer-dist/assets/ayu-light-C3h-C4tm.js +1 -0
  95. package/viewer-dist/assets/ayu-light-DSkcX_XD.js +1 -0
  96. package/viewer-dist/assets/ayu-mirage-Bqwy1Gya.js +1 -0
  97. package/viewer-dist/assets/ayu-mirage-DSve0zuE.js +1 -0
  98. package/viewer-dist/assets/ballerina-B7ZEbQpA.js +1 -0
  99. package/viewer-dist/assets/bat-qdxAdBWQ.js +1 -0
  100. package/viewer-dist/assets/beancount-C2IN4Vk8.js +1 -0
  101. package/viewer-dist/assets/berry-DKpUyyne.js +1 -0
  102. package/viewer-dist/assets/bibtex-Ci_nEsc7.js +1 -0
  103. package/viewer-dist/assets/bicep-CUHmPFLl.js +1 -0
  104. package/viewer-dist/assets/bird2-CYIUgYqB.js +1 -0
  105. package/viewer-dist/assets/blade-B5YUZNEG.js +1 -0
  106. package/viewer-dist/assets/bsl-_VjlB9mv.js +1 -0
  107. package/viewer-dist/assets/c-BNQJhXlP.js +1 -0
  108. package/viewer-dist/assets/c3-D0apG41V.js +1 -0
  109. package/viewer-dist/assets/cadence-CQ2zXKGN.js +1 -0
  110. package/viewer-dist/assets/cairo-DLTphjLi.js +1 -0
  111. package/viewer-dist/assets/catppuccin-frappe-C9Q5zVZY.js +1 -0
  112. package/viewer-dist/assets/catppuccin-frappe-DbLkF0J2.js +1 -0
  113. package/viewer-dist/assets/catppuccin-latte-CtsyrtPq.js +1 -0
  114. package/viewer-dist/assets/catppuccin-latte-b6208YQK.js +1 -0
  115. package/viewer-dist/assets/catppuccin-macchiato-CNNBbV1L.js +1 -0
  116. package/viewer-dist/assets/catppuccin-macchiato-R8nAf1vR.js +1 -0
  117. package/viewer-dist/assets/catppuccin-mocha-DHkNF0Mp.js +1 -0
  118. package/viewer-dist/assets/catppuccin-mocha-DjuaAJKi.js +1 -0
  119. package/viewer-dist/assets/chapel-CFMD-Djs.js +1 -0
  120. package/viewer-dist/assets/clarity-CtfBBspg.js +1 -0
  121. package/viewer-dist/assets/clojure-DqKBuwfJ.js +1 -0
  122. package/viewer-dist/assets/cmake-Bj61d0ZC.js +1 -0
  123. package/viewer-dist/assets/cobol-DY6IFdmX.js +1 -0
  124. package/viewer-dist/assets/codeowners-C8r90Shi.js +1 -0
  125. package/viewer-dist/assets/codeql-oeQT6MSM.js +1 -0
  126. package/viewer-dist/assets/coffee-BP03ytLP.js +1 -0
  127. package/viewer-dist/assets/commit-mono-latin-400-italic-BXinMwCi.woff +0 -0
  128. package/viewer-dist/assets/commit-mono-latin-400-italic-DjSHLl2N.woff2 +0 -0
  129. package/viewer-dist/assets/commit-mono-latin-400-normal-s0S3qwFW.woff +0 -0
  130. package/viewer-dist/assets/commit-mono-latin-400-normal-wzhe4RuD.woff2 +0 -0
  131. package/viewer-dist/assets/common-lisp-Cv5bFMCO.js +1 -0
  132. package/viewer-dist/assets/coq-CGaSfhwR.js +1 -0
  133. package/viewer-dist/assets/core-BkcJpkJE.js +4 -0
  134. package/viewer-dist/assets/cpp-CUBNVKxn.js +1 -0
  135. package/viewer-dist/assets/crystal-NSr8mDkd.js +1 -0
  136. package/viewer-dist/assets/csharp-dmMxLVLW.js +1 -0
  137. package/viewer-dist/assets/css-BiJUKRHp.js +1 -0
  138. package/viewer-dist/assets/csv-Dx-8-gkx.js +1 -0
  139. package/viewer-dist/assets/cue-CE9AQfxI.js +1 -0
  140. package/viewer-dist/assets/cypher-ClKdZ_lG.js +1 -0
  141. package/viewer-dist/assets/d-qD-0Kul2.js +1 -0
  142. package/viewer-dist/assets/dark-plus-BVZ_4wTZ.js +1 -0
  143. package/viewer-dist/assets/dark-plus-Cs2F2srj.js +1 -0
  144. package/viewer-dist/assets/dart-CHZY9Xhz.js +1 -0
  145. package/viewer-dist/assets/dax-BkyTk9wS.js +1 -0
  146. package/viewer-dist/assets/desktop-Dlh5hvp9.js +1 -0
  147. package/viewer-dist/assets/diff-woXpYk--.js +1 -0
  148. package/viewer-dist/assets/docker-IyjqRm3v.js +1 -0
  149. package/viewer-dist/assets/dotenv-CuH5my32.js +1 -0
  150. package/viewer-dist/assets/dracula-BHWKrbxM.js +1 -0
  151. package/viewer-dist/assets/dracula-BoZgXveB.js +1 -0
  152. package/viewer-dist/assets/dracula-soft-5eyTD99u.js +1 -0
  153. package/viewer-dist/assets/dracula-soft-D-Kgh5gw.js +1 -0
  154. package/viewer-dist/assets/dream-maker-DW3nJb8Q.js +1 -0
  155. package/viewer-dist/assets/edge-DznSXZdq.js +1 -0
  156. package/viewer-dist/assets/elixir-D1HcpP2u.js +1 -0
  157. package/viewer-dist/assets/elk.bundled-CVOErv1M.js +24 -0
  158. package/viewer-dist/assets/elm-Bmx6Fs0i.js +1 -0
  159. package/viewer-dist/assets/emacs-lisp-DR2vtWaj.js +1 -0
  160. package/viewer-dist/assets/engine-javascript-BopS6peh.js +141 -0
  161. package/viewer-dist/assets/engine-oniguruma-BO8SA_1o.js +1 -0
  162. package/viewer-dist/assets/erb-CdvLbCTI.js +1 -0
  163. package/viewer-dist/assets/erlang-Cphh6RMH.js +1 -0
  164. package/viewer-dist/assets/everforest-dark-Y6tr-2zD.js +1 -0
  165. package/viewer-dist/assets/everforest-dark-sB-x3p7T.js +1 -0
  166. package/viewer-dist/assets/everforest-light-CA0Ol4Qu.js +1 -0
  167. package/viewer-dist/assets/everforest-light-Df2xbC6M.js +1 -0
  168. package/viewer-dist/assets/fennel-DQxkIbk2.js +1 -0
  169. package/viewer-dist/assets/fish-BJitypiv.js +1 -0
  170. package/viewer-dist/assets/fluent-C03EYrpw.js +1 -0
  171. package/viewer-dist/assets/fortran-fixed-form-DEKoE2YW.js +1 -0
  172. package/viewer-dist/assets/fortran-free-form-CYNrtFtB.js +1 -0
  173. package/viewer-dist/assets/fsharp-D13ZGOAj.js +1 -0
  174. package/viewer-dist/assets/gdresource-xMC7jr7x.js +1 -0
  175. package/viewer-dist/assets/gdscript-DYvRD3hg.js +1 -0
  176. package/viewer-dist/assets/gdshader-CBce3t8t.js +1 -0
  177. package/viewer-dist/assets/genie-CV2tkWYe.js +1 -0
  178. package/viewer-dist/assets/gherkin-DExj1W_8.js +1 -0
  179. package/viewer-dist/assets/git-commit-BSykSTBG.js +1 -0
  180. package/viewer-dist/assets/git-rebase-C-RR1FSc.js +1 -0
  181. package/viewer-dist/assets/github-dark-C-LZuMrd.js +1 -0
  182. package/viewer-dist/assets/github-dark-C895GGrm.js +1 -0
  183. package/viewer-dist/assets/github-dark-default-DXG-b-1a.js +1 -0
  184. package/viewer-dist/assets/github-dark-default-adAWTKmX.js +1 -0
  185. package/viewer-dist/assets/github-dark-dimmed-Bx1FflLF.js +1 -0
  186. package/viewer-dist/assets/github-dark-dimmed-jPx1V1fR.js +1 -0
  187. package/viewer-dist/assets/github-dark-high-contrast-B_tTalzw.js +1 -0
  188. package/viewer-dist/assets/github-dark-high-contrast-UN5YjL_Z.js +1 -0
  189. package/viewer-dist/assets/github-light-B4HDwToD.js +1 -0
  190. package/viewer-dist/assets/github-light-EUqPIrTm.js +1 -0
  191. package/viewer-dist/assets/github-light-default-BXViO-2h.js +1 -0
  192. package/viewer-dist/assets/github-light-default-CfC59JYV.js +1 -0
  193. package/viewer-dist/assets/github-light-high-contrast-B68TUdTA.js +1 -0
  194. package/viewer-dist/assets/github-light-high-contrast-C3edEHcK.js +1 -0
  195. package/viewer-dist/assets/gleam-CSRkHgEL.js +1 -0
  196. package/viewer-dist/assets/glimmer-js-BUse42ki.js +1 -0
  197. package/viewer-dist/assets/glimmer-ts-zH_nSjyx.js +1 -0
  198. package/viewer-dist/assets/glsl-CyFpZtQv.js +1 -0
  199. package/viewer-dist/assets/gn-CAXYAgV-.js +1 -0
  200. package/viewer-dist/assets/gnuplot-7GGW24-e.js +1 -0
  201. package/viewer-dist/assets/go-rLFTqkRN.js +1 -0
  202. package/viewer-dist/assets/graphql-BIyAKkG2.js +1 -0
  203. package/viewer-dist/assets/groovy-CacY0gHj.js +1 -0
  204. package/viewer-dist/assets/gruvbox-dark-hard-BdGOuxq8.js +1 -0
  205. package/viewer-dist/assets/gruvbox-dark-hard-C820rvS2.js +1 -0
  206. package/viewer-dist/assets/gruvbox-dark-medium-BPjhmG05.js +1 -0
  207. package/viewer-dist/assets/gruvbox-dark-medium-CmygtSMi.js +1 -0
  208. package/viewer-dist/assets/gruvbox-dark-soft-BJH4XuY9.js +1 -0
  209. package/viewer-dist/assets/gruvbox-dark-soft-MrdJrrXF.js +1 -0
  210. package/viewer-dist/assets/gruvbox-light-hard-BC_s9l72.js +1 -0
  211. package/viewer-dist/assets/gruvbox-light-hard-BkSILF4E.js +1 -0
  212. package/viewer-dist/assets/gruvbox-light-medium-BAWPOn9u.js +1 -0
  213. package/viewer-dist/assets/gruvbox-light-medium-DiZUfgdz.js +1 -0
  214. package/viewer-dist/assets/gruvbox-light-soft-BSMLrYjP.js +1 -0
  215. package/viewer-dist/assets/gruvbox-light-soft-CRCTnbIj.js +1 -0
  216. package/viewer-dist/assets/hack-qk6BiceN.js +1 -0
  217. package/viewer-dist/assets/haml-BkBm6IgF.js +1 -0
  218. package/viewer-dist/assets/handlebars-FMeV8O-Z.js +1 -0
  219. package/viewer-dist/assets/haskell-D8IpX4py.js +1 -0
  220. package/viewer-dist/assets/haxe-C8oCnwJJ.js +1 -0
  221. package/viewer-dist/assets/hcl-Dh228itO.js +1 -0
  222. package/viewer-dist/assets/highlights-NUSPeu9U.js +3 -0
  223. package/viewer-dist/assets/hjson-CxZEssPk.js +1 -0
  224. package/viewer-dist/assets/hlsl-Cvrh5tZx.js +1 -0
  225. package/viewer-dist/assets/horizon-CE9ld1lL.js +1 -0
  226. package/viewer-dist/assets/horizon-DUI96lQn.js +1 -0
  227. package/viewer-dist/assets/horizon-bright-COxh1lHf.js +1 -0
  228. package/viewer-dist/assets/horizon-bright-DSNQnXHK.js +1 -0
  229. package/viewer-dist/assets/houston-CsvMBhTu.js +1 -0
  230. package/viewer-dist/assets/houston-DduE73P7.js +1 -0
  231. package/viewer-dist/assets/html-CvoVzlT3.js +1 -0
  232. package/viewer-dist/assets/html-derivative-CmO0_REm.js +1 -0
  233. package/viewer-dist/assets/http-c4_vT9ST.js +1 -0
  234. package/viewer-dist/assets/hurl-BqZA9I9Q.js +1 -0
  235. package/viewer-dist/assets/hxml-Dcm88srW.js +1 -0
  236. package/viewer-dist/assets/hy-CZbG8q4J.js +1 -0
  237. package/viewer-dist/assets/imba-DsUTQ-LC.js +1 -0
  238. package/viewer-dist/assets/index-B0ZrAosS.css +1 -0
  239. package/viewer-dist/assets/index-C8Oxwcs8.js +264 -0
  240. package/viewer-dist/assets/ini-B5eOa1yu.js +1 -0
  241. package/viewer-dist/assets/java-D7h0NA_A.js +1 -0
  242. package/viewer-dist/assets/javascript-DcMHgNcu.js +1 -0
  243. package/viewer-dist/assets/jinja-IxhZJXij.js +1 -0
  244. package/viewer-dist/assets/jison-Ru_S5AEn.js +1 -0
  245. package/viewer-dist/assets/json-DePJdKYk.js +1 -0
  246. package/viewer-dist/assets/json5-BR5RXkoi.js +1 -0
  247. package/viewer-dist/assets/jsonc-CYpm1nAK.js +1 -0
  248. package/viewer-dist/assets/jsonl-CmCQp5Yx.js +1 -0
  249. package/viewer-dist/assets/jsonnet-CJTPZ8u_.js +1 -0
  250. package/viewer-dist/assets/jssm-DXw9l8Rf.js +1 -0
  251. package/viewer-dist/assets/jsx-BUUYi3qs.js +1 -0
  252. package/viewer-dist/assets/julia-BuaSHoYZ.js +1 -0
  253. package/viewer-dist/assets/just-BJW1YJYB.js +1 -0
  254. package/viewer-dist/assets/kanagawa-dragon-BHDhSKDf.js +1 -0
  255. package/viewer-dist/assets/kanagawa-dragon-Bozd7klA.js +1 -0
  256. package/viewer-dist/assets/kanagawa-lotus-BmuOG9ZW.js +1 -0
  257. package/viewer-dist/assets/kanagawa-lotus-NJjGXXql.js +1 -0
  258. package/viewer-dist/assets/kanagawa-wave-BML5mF2J.js +1 -0
  259. package/viewer-dist/assets/kanagawa-wave-DsGe2Uqk.js +1 -0
  260. package/viewer-dist/assets/kdl-CsD5j6eV.js +1 -0
  261. package/viewer-dist/assets/kotlin-DhhofPvG.js +1 -0
  262. package/viewer-dist/assets/kusto-C7mF5XQf.js +1 -0
  263. package/viewer-dist/assets/langs-Di6vPLUk.js +2 -0
  264. package/viewer-dist/assets/laserwave-C_8bwKvT.js +1 -0
  265. package/viewer-dist/assets/laserwave-DYV0fvJ_.js +1 -0
  266. package/viewer-dist/assets/latex-B6yY1rfM.js +1 -0
  267. package/viewer-dist/assets/lean-CewbzKMR.js +1 -0
  268. package/viewer-dist/assets/less-DVTAwKKz.js +1 -0
  269. package/viewer-dist/assets/light-plus-DVQuIRkW.js +1 -0
  270. package/viewer-dist/assets/light-plus-FTnIShls.js +1 -0
  271. package/viewer-dist/assets/liquid-DNgNMjPq.js +1 -0
  272. package/viewer-dist/assets/llvm-DqHOMS-s.js +1 -0
  273. package/viewer-dist/assets/loader-Cvp9wZb2.js +1 -0
  274. package/viewer-dist/assets/log-BNLmms1o.js +1 -0
  275. package/viewer-dist/assets/logo-Cluzi2Zq.js +1 -0
  276. package/viewer-dist/assets/lua-Z49wBRLR.js +1 -0
  277. package/viewer-dist/assets/luau-VGWVLoqX.js +1 -0
  278. package/viewer-dist/assets/make-Dixweg8N.js +1 -0
  279. package/viewer-dist/assets/markdown-BYOwaDjH.js +1 -0
  280. package/viewer-dist/assets/marko-i5cBncq8.js +1 -0
  281. package/viewer-dist/assets/material-theme-Bm3Qr25_.js +1 -0
  282. package/viewer-dist/assets/material-theme-IcIb8QNx.js +1 -0
  283. package/viewer-dist/assets/material-theme-darker-2IIEA8gg.js +1 -0
  284. package/viewer-dist/assets/material-theme-darker-B_f2vxdL.js +1 -0
  285. package/viewer-dist/assets/material-theme-lighter-CR2Q-4Hp.js +1 -0
  286. package/viewer-dist/assets/material-theme-lighter-uhdI0v04.js +1 -0
  287. package/viewer-dist/assets/material-theme-ocean-BX6hAJ_y.js +1 -0
  288. package/viewer-dist/assets/material-theme-ocean-CHQ94UKr.js +1 -0
  289. package/viewer-dist/assets/material-theme-palenight-B5W6OYN7.js +1 -0
  290. package/viewer-dist/assets/material-theme-palenight-B6DWAotd.js +1 -0
  291. package/viewer-dist/assets/matlab-D7qyCx1q.js +1 -0
  292. package/viewer-dist/assets/mdc-C3wRYKz5.js +1 -0
  293. package/viewer-dist/assets/mdx-DQZ5AkYe.js +1 -0
  294. package/viewer-dist/assets/mermaid-BxpfTIzt.js +1 -0
  295. package/viewer-dist/assets/min-dark-BSWPekZh.js +1 -0
  296. package/viewer-dist/assets/min-dark-DECtZcqS.js +1 -0
  297. package/viewer-dist/assets/min-light-DDpmG2fV.js +1 -0
  298. package/viewer-dist/assets/min-light-qRIVcaqf.js +1 -0
  299. package/viewer-dist/assets/mipsasm-BMqwQI7S.js +1 -0
  300. package/viewer-dist/assets/mojo-fg40_ntQ.js +1 -0
  301. package/viewer-dist/assets/monokai-BscAjiQZ.js +1 -0
  302. package/viewer-dist/assets/monokai-CLmrJ-8t.js +1 -0
  303. package/viewer-dist/assets/moonbit-D9W784E_.js +1 -0
  304. package/viewer-dist/assets/move-BYnGhZoM.js +1 -0
  305. package/viewer-dist/assets/narrat-_X_XdTYD.js +1 -0
  306. package/viewer-dist/assets/nextflow-CSgcYZcx.js +1 -0
  307. package/viewer-dist/assets/nextflow-groovy-D7IRt6Pp.js +1 -0
  308. package/viewer-dist/assets/nginx-BrbrEdla.js +1 -0
  309. package/viewer-dist/assets/night-owl-DhmEMT88.js +1 -0
  310. package/viewer-dist/assets/night-owl-eR4AsyAP.js +1 -0
  311. package/viewer-dist/assets/night-owl-light-C74n5ti-.js +1 -0
  312. package/viewer-dist/assets/night-owl-light-eJ-hLW7d.js +1 -0
  313. package/viewer-dist/assets/nim-BCe7ZKXY.js +1 -0
  314. package/viewer-dist/assets/nix-IvuFDN5E.js +1 -0
  315. package/viewer-dist/assets/nord-Cb4Vim4T.js +1 -0
  316. package/viewer-dist/assets/nord-D4wy7NEP.js +1 -0
  317. package/viewer-dist/assets/nsis-CjNLYCLg.js +1 -0
  318. package/viewer-dist/assets/nushell--0fT3PI1.js +1 -0
  319. package/viewer-dist/assets/objective-c-D1A_Heim.js +1 -0
  320. package/viewer-dist/assets/objective-cpp-BsSzOQcm.js +1 -0
  321. package/viewer-dist/assets/ocaml-O90oeIOV.js +1 -0
  322. package/viewer-dist/assets/odin-B1RWQWA5.js +1 -0
  323. package/viewer-dist/assets/one-dark-pro-28TLzoS8.js +1 -0
  324. package/viewer-dist/assets/one-dark-pro-C6YyR8OD.js +1 -0
  325. package/viewer-dist/assets/one-light-C0UY_Fh7.js +1 -0
  326. package/viewer-dist/assets/one-light-D7Lr4KcI.js +1 -0
  327. package/viewer-dist/assets/openscad-BUDT5pXO.js +1 -0
  328. package/viewer-dist/assets/org-DDCXkPsd.js +1 -0
  329. package/viewer-dist/assets/pascal-4ZHwLPI5.js +1 -0
  330. package/viewer-dist/assets/perl-DLhC7S_Q.js +1 -0
  331. package/viewer-dist/assets/php-CDzTReqR.js +1 -0
  332. package/viewer-dist/assets/pierre-dark-CpLgRqie.js +1 -0
  333. package/viewer-dist/assets/pierre-dark-fPlffE7i.js +1 -0
  334. package/viewer-dist/assets/pierre-dark-protanopia-deuteranopia-B35FxJx-.js +1 -0
  335. package/viewer-dist/assets/pierre-dark-protanopia-deuteranopia-BmjibgrW.js +1 -0
  336. package/viewer-dist/assets/pierre-dark-soft-Cng2SYKc.js +1 -0
  337. package/viewer-dist/assets/pierre-dark-soft-kZQmAZld.js +1 -0
  338. package/viewer-dist/assets/pierre-dark-tritanopia-CpjhbsIL.js +1 -0
  339. package/viewer-dist/assets/pierre-dark-tritanopia-DneQ5i7L.js +1 -0
  340. package/viewer-dist/assets/pierre-dark-vibrant-BUK9Y-N_.js +1 -0
  341. package/viewer-dist/assets/pierre-dark-vibrant-CpQYzh95.js +1 -0
  342. package/viewer-dist/assets/pierre-light-BvcXQJIj.js +1 -0
  343. package/viewer-dist/assets/pierre-light-CoaEpmwp.js +1 -0
  344. package/viewer-dist/assets/pierre-light-protanopia-deuteranopia-0fSaH845.js +1 -0
  345. package/viewer-dist/assets/pierre-light-protanopia-deuteranopia-Cd5nk0bp.js +1 -0
  346. package/viewer-dist/assets/pierre-light-soft-BvU23vks.js +1 -0
  347. package/viewer-dist/assets/pierre-light-soft-lWLdNTOI.js +1 -0
  348. package/viewer-dist/assets/pierre-light-tritanopia-BSHccQzI.js +1 -0
  349. package/viewer-dist/assets/pierre-light-tritanopia-CEbqgOJL.js +1 -0
  350. package/viewer-dist/assets/pierre-light-vibrant-BgMZEwQI.js +1 -0
  351. package/viewer-dist/assets/pierre-light-vibrant-D80Fkn33.js +1 -0
  352. package/viewer-dist/assets/pkl-ot-7Btpt.js +1 -0
  353. package/viewer-dist/assets/plastic-B2V_PDVk.js +1 -0
  354. package/viewer-dist/assets/plastic-DQwYfKfQ.js +1 -0
  355. package/viewer-dist/assets/plsql-DGHpHOYJ.js +1 -0
  356. package/viewer-dist/assets/po-BiJDBrnU.js +1 -0
  357. package/viewer-dist/assets/poimandres-DB9-pI6r.js +1 -0
  358. package/viewer-dist/assets/poimandres-DRFjx7u4.js +1 -0
  359. package/viewer-dist/assets/polar-C7UOKdEL.js +1 -0
  360. package/viewer-dist/assets/postcss-BXeXVLqQ.js +1 -0
  361. package/viewer-dist/assets/powerquery-DNMTfnFr.js +1 -0
  362. package/viewer-dist/assets/powershell-QtSnmXcu.js +1 -0
  363. package/viewer-dist/assets/prisma-DMgNhnYS.js +1 -0
  364. package/viewer-dist/assets/prolog-iXnhIJG7.js +1 -0
  365. package/viewer-dist/assets/proto-DB4EqR-F.js +1 -0
  366. package/viewer-dist/assets/pug-COoI2o4U.js +1 -0
  367. package/viewer-dist/assets/puppet-CDv2pdJW.js +1 -0
  368. package/viewer-dist/assets/purescript-9MfHhQsQ.js +1 -0
  369. package/viewer-dist/assets/python-gzcpVVnB.js +1 -0
  370. package/viewer-dist/assets/qml-g4UDed-8.js +1 -0
  371. package/viewer-dist/assets/qmldir-DCQb3MpD.js +1 -0
  372. package/viewer-dist/assets/qss-Fe1Jh2GI.js +1 -0
  373. package/viewer-dist/assets/r-CvCSiWB_.js +1 -0
  374. package/viewer-dist/assets/racket-DcIDlBhZ.js +1 -0
  375. package/viewer-dist/assets/raku-B3gFvitq.js +1 -0
  376. package/viewer-dist/assets/razor-BRLDaw7i.js +1 -0
  377. package/viewer-dist/assets/rbs-C0MpOrj4.js +1 -0
  378. package/viewer-dist/assets/red-CYlAq2b0.js +1 -0
  379. package/viewer-dist/assets/red-CqYzoXtd.js +1 -0
  380. package/viewer-dist/assets/reg-CRGYupPL.js +1 -0
  381. package/viewer-dist/assets/regexp-I2jnduhj.js +1 -0
  382. package/viewer-dist/assets/rel-BtDbiS_P.js +1 -0
  383. package/viewer-dist/assets/riscv-Ckw8ddFX.js +1 -0
  384. package/viewer-dist/assets/rolldown-runtime-Dd_uD5pT.js +1 -0
  385. package/viewer-dist/assets/ron-VUp2lXgN.js +1 -0
  386. package/viewer-dist/assets/rose-pine-C3zjVKxG.js +1 -0
  387. package/viewer-dist/assets/rose-pine-aMsaMD1D.js +1 -0
  388. package/viewer-dist/assets/rose-pine-dawn-8PwUyIlP.js +1 -0
  389. package/viewer-dist/assets/rose-pine-dawn-C72QYfqa.js +1 -0
  390. package/viewer-dist/assets/rose-pine-moon-CSM8ewhO.js +1 -0
  391. package/viewer-dist/assets/rose-pine-moon-DO-qXg-I.js +1 -0
  392. package/viewer-dist/assets/rosmsg-CAekHB0j.js +1 -0
  393. package/viewer-dist/assets/rst-BEQnCgL0.js +1 -0
  394. package/viewer-dist/assets/ruby-COXzLN2W.js +1 -0
  395. package/viewer-dist/assets/rust-DpiIf5JO.js +1 -0
  396. package/viewer-dist/assets/sas-Cr47JhdL.js +1 -0
  397. package/viewer-dist/assets/sass-DXrisJhu.js +1 -0
  398. package/viewer-dist/assets/scala-BiFt_7mu.js +1 -0
  399. package/viewer-dist/assets/scheme-DQCgrYNe.js +1 -0
  400. package/viewer-dist/assets/scss-BuNb6cgZ.js +1 -0
  401. package/viewer-dist/assets/sdbl-bTVj8UrX.js +1 -0
  402. package/viewer-dist/assets/shaderlab-TOUzSsQk.js +1 -0
  403. package/viewer-dist/assets/shellscript-B51zB43X.js +1 -0
  404. package/viewer-dist/assets/shellsession-B-KBpmJs.js +1 -0
  405. package/viewer-dist/assets/shiki-CTIyHrkn.js +2 -0
  406. package/viewer-dist/assets/slack-dark-DnToyrRv.js +1 -0
  407. package/viewer-dist/assets/slack-dark-Dtzi51su.js +1 -0
  408. package/viewer-dist/assets/slack-ochin-B2OO5cIa.js +1 -0
  409. package/viewer-dist/assets/slack-ochin-Bb7oPExa.js +1 -0
  410. package/viewer-dist/assets/smalltalk-BHpQb5nM.js +1 -0
  411. package/viewer-dist/assets/smithy-Dgaz7aur.js +1 -0
  412. package/viewer-dist/assets/snazzy-light-4G7pJPwS.js +1 -0
  413. package/viewer-dist/assets/snazzy-light-DXgiwzKu.js +1 -0
  414. package/viewer-dist/assets/solarized-dark-BKOT3ICq.js +1 -0
  415. package/viewer-dist/assets/solarized-dark-b97czJOk.js +1 -0
  416. package/viewer-dist/assets/solarized-light--Lk5pOfE.js +1 -0
  417. package/viewer-dist/assets/solarized-light-DFPxpIYQ.js +1 -0
  418. package/viewer-dist/assets/solidity-Bj7E1mRn.js +1 -0
  419. package/viewer-dist/assets/soy-B-X4e_cm.js +1 -0
  420. package/viewer-dist/assets/sparql-D_iOobhT.js +1 -0
  421. package/viewer-dist/assets/splunk-BC2Px7Mm.js +1 -0
  422. package/viewer-dist/assets/sql-CrePkbX5.js +1 -0
  423. package/viewer-dist/assets/ssh-config-BgfXC-Er.js +1 -0
  424. package/viewer-dist/assets/stata-LQMPNdRb.js +1 -0
  425. package/viewer-dist/assets/stream-tokenizer-8imCpDcl.js +4 -0
  426. package/viewer-dist/assets/stylus-B6D30XZt.js +1 -0
  427. package/viewer-dist/assets/surrealql-DalIYx4r.js +1 -0
  428. package/viewer-dist/assets/svelte-CutSaB0m.js +1 -0
  429. package/viewer-dist/assets/swift-CyEgAFGc.js +1 -0
  430. package/viewer-dist/assets/synthwave-84-BJJFg-sc.js +1 -0
  431. package/viewer-dist/assets/synthwave-84-nFMaYfgc.js +1 -0
  432. package/viewer-dist/assets/system-verilog-Dh5ihWbf.js +1 -0
  433. package/viewer-dist/assets/systemd-BxMlprV5.js +1 -0
  434. package/viewer-dist/assets/talonscript-CohzipZa.js +1 -0
  435. package/viewer-dist/assets/tasl-DMoTqEGO.js +1 -0
  436. package/viewer-dist/assets/tcl-CZd0xW_V.js +1 -0
  437. package/viewer-dist/assets/templ-STIZV9cS.js +1 -0
  438. package/viewer-dist/assets/terraform-DswuEJGm.js +1 -0
  439. package/viewer-dist/assets/tex-JPaUWOrn.js +1 -0
  440. package/viewer-dist/assets/themes-CGzFOfgV.js +2 -0
  441. package/viewer-dist/assets/tokyo-night-DvpptEDd.js +1 -0
  442. package/viewer-dist/assets/tokyo-night-oM2G3aXe.js +1 -0
  443. package/viewer-dist/assets/toml-CcmNWLt0.js +1 -0
  444. package/viewer-dist/assets/ts-tags-DugY2c1f.js +1 -0
  445. package/viewer-dist/assets/tsv-sltzmVWM.js +1 -0
  446. package/viewer-dist/assets/tsx-DvWhG4dC.js +1 -0
  447. package/viewer-dist/assets/turtle-ByJddavk.js +1 -0
  448. package/viewer-dist/assets/twig-CAQ2meH1.js +1 -0
  449. package/viewer-dist/assets/typescript-BTGs5etX.js +1 -0
  450. package/viewer-dist/assets/typespec-BGhR2SqG.js +1 -0
  451. package/viewer-dist/assets/typst-D2auzO0m.js +1 -0
  452. package/viewer-dist/assets/v-DBj4K9d_.js +1 -0
  453. package/viewer-dist/assets/vala-zf12oZj6.js +1 -0
  454. package/viewer-dist/assets/vb-DOwzaHZ0.js +1 -0
  455. package/viewer-dist/assets/verilog-B2gwz-sJ.js +1 -0
  456. package/viewer-dist/assets/vesper-C1rBZbON.js +1 -0
  457. package/viewer-dist/assets/vesper-DdrHHSXu.js +1 -0
  458. package/viewer-dist/assets/vhdl-BroJfC0k.js +1 -0
  459. package/viewer-dist/assets/viml-DvXPmvsu.js +1 -0
  460. package/viewer-dist/assets/vitesse-black-Sqvrs2Sw.js +1 -0
  461. package/viewer-dist/assets/vitesse-black-fwtXNY1n.js +1 -0
  462. package/viewer-dist/assets/vitesse-dark-BWf_ZQtP.js +1 -0
  463. package/viewer-dist/assets/vitesse-dark-BZCL-v6S.js +1 -0
  464. package/viewer-dist/assets/vitesse-light-Cqenv4Qv.js +1 -0
  465. package/viewer-dist/assets/vitesse-light-VbXTXTou.js +1 -0
  466. package/viewer-dist/assets/vue-Bu9nv_eN.js +1 -0
  467. package/viewer-dist/assets/vue-html-BXjKVtKk.js +1 -0
  468. package/viewer-dist/assets/vue-vine-Ci2qndh_.js +1 -0
  469. package/viewer-dist/assets/vyper-CgoNMtux.js +1 -0
  470. package/viewer-dist/assets/wasm-BnjxR4X6.js +1 -0
  471. package/viewer-dist/assets/wasm-ByWQv1Qj.js +1 -0
  472. package/viewer-dist/assets/wenyan-C8pVoKbM.js +1 -0
  473. package/viewer-dist/assets/wgsl-BsKzXJz4.js +1 -0
  474. package/viewer-dist/assets/wikitext-ClFFjSW2.js +1 -0
  475. package/viewer-dist/assets/wit-DdvCle-K.js +1 -0
  476. package/viewer-dist/assets/wolfram-DLL8P-h_.js +1 -0
  477. package/viewer-dist/assets/xml-C01ajBW7.js +1 -0
  478. package/viewer-dist/assets/xsl-CCLNyvR3.js +1 -0
  479. package/viewer-dist/assets/yaml-BWCS3NLV.js +1 -0
  480. package/viewer-dist/assets/zenscript-BnlCZFoB.js +1 -0
  481. package/viewer-dist/assets/zig-CMLA9XwU.js +1 -0
  482. package/viewer-dist/index.html +71 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Tanishq Kancharla
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,576 @@
1
- # Temporary Holding Version
1
+ # productdoc
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Understand the system, decide what to build, and review what changed.** Productdoc turns your coding agent's findings into visual documents, with diagrams, media, and source links behind the reasoning.
4
+
5
+ Use it to explain an existing workflow, plan future work, or review a change. Documents start with the reader's question and familiar UI or involved services—not automatically with code. Plans keep one small, independent or commit-sized change per page.
6
+
7
+ ## Try it
8
+
9
+ The `product-doc` CLI is available on npm, and the `generate-product-doc` skill is available in this public repository. You need Git, Node.js 22 or newer, npm, and a coding agent with repository and shell access.
10
+
11
+ From your project, ask your agent:
12
+
13
+ ```text
14
+ Install the generate-product-doc skill from tanishqkancharla/diffmap, then use it to explain how this project works.
15
+ ```
16
+
17
+ Or install the skill yourself, selecting your coding agent when prompted:
18
+
19
+ ```sh
20
+ npx skills add tanishqkancharla/diffmap --skill generate-product-doc
21
+ ```
22
+
23
+ For a non-interactive Amp installation, add `--agent amp --yes`. Then ask your agent to use `generate-product-doc` to explain a system, plan work, or review changes. If the current session does not discover the installed skill, reload its skills or start a new session.
24
+
25
+ Installing the skill and acquiring the CLI are separate steps. The skill is a short pointer: your agent loads the full instructions from `npx product-doc guide`, which acquires the CLI from npm and keeps its instructions version-matched to the viewer. Running that command alone does not install the skill. When the stub itself changes, update it with `npx skills update generate-product-doc`.
26
+
27
+ The skill keeps documents in `.diffmap/specs/<name>/`. Productdoc is open source and MIT licensed. Documents are served locally by default; [sharing as an unlisted gist](#share-a-spec-with-a-link-experimental) still uses diffmap.dev until productdoc.dev supports those links.
28
+
29
+ ### Migrating from Diffmap
30
+
31
+ Productdoc is the standalone successor to Diffmap, expanding beyond diff review. The npm package is `product-doc`, its executable is `product-doc`, and its website is [productdoc.dev](https://productdoc.dev). The GitHub repository keeps its current URL.
32
+
33
+ Diffmap is being retired. Use `generate-product-doc` and `product-doc` for new work, not the legacy skill or package. Existing installs do not migrate automatically. Keep existing documents and shared links rather than copying or deleting them; Productdoc still reads `.diffmap/specs/`. No legacy binary alias or automatic installation migration is added.
34
+
35
+ [The original Diffmap launch video](https://x.com/tanishqk/status/2116212881125691850) shows the review workflow this builds on.
36
+
37
+ ## See the main ideas
38
+
39
+ Your agent picks the best diagram for each idea, and each part of a diagram links to its code. [diffmap.dev](https://diffmap.dev) walks through each one on an example pull request.
40
+
41
+ ### Service diagrams
42
+
43
+ A service diagram shows each service and its state. Each step shows one event and the state that the event changes, so you do not have to remember the state. Press **Play** to step through it. See [Animated service diagrams](#animated-service-diagrams) for the syntax.
44
+
45
+ ![A service diagram stepping through how a client reopens a saved agent's thread](media/service-diagram.webp)
46
+
47
+ ### Diagram and call stack diffs
48
+
49
+ A Mermaid or service diagram can show a change in one picture: red parts exist only today, and green parts are new. In a service diagram diff, each value shows today's state crossed out next to the new state. Call stacks show a change the same way, with `+` rows for new code and `-` rows for code the change removes. See [Diagram diffs](#diagram-diffs).
50
+
51
+ ![Mermaid flowchart, sequence, and service diagram diffs for moving sessions from an in-memory cache to Postgres](media/diagram-diffs.webp)
52
+
53
+ ### Phases and commits
54
+
55
+ A spec is a directory with a cover page and one page per phase. The agent writes the plan in phases, each small enough to be one commit. When a phase is done, the spec shows a card for its commit with the files to review, most important first. Click a file to open its diff. Every link in the phase then points at that commit, so it keeps showing the code from that commit after the file changes.
56
+
57
+ ![A finished phase's commit card, with a file opening in the Diff panel](media/phase-commits.webp)
58
+
59
+ ### Comments
60
+
61
+ Highlight text on the page and press **Comment** to leave a note beside it.
62
+ In a diff, file excerpt, or the Diff panel, hover a line and press the **+**
63
+ in the gutter, or drag it across several lines, to comment under those lines.
64
+ Comments save in your browser (localStorage, per page) and survive reloads.
65
+ **Copy comments** in the top right copies them all as a numbered Markdown list,
66
+ each with its location and the quoted text or lines, ready to paste to an
67
+ agent. ⌘/Ctrl-Enter saves a comment and Escape cancels it.
68
+
69
+ ![Leaving comments on a spec and its diff, then copying them for the agent](media/comments.webp)
70
+
71
+ ## Run the viewer
72
+
73
+ ```sh
74
+ npx product-doc serve .diffmap/specs/<name>/
75
+ ```
76
+
77
+ Bare `npx product-doc .diffmap/specs/<name>/` is the same as `serve`. A spec is always a directory; `serve`, `validate`, and `share` reject a single Markdown file and say where to move it.
78
+
79
+ Options:
80
+
81
+ - `--port <n>` — pin a listen port (default: a free port)
82
+ - `--root <dir>` — workspace root for file excerpts (default the directory you ran the command from)
83
+
84
+ **Close server** in the top right stops the server. Hosted gist and GitHub viewers have no local server, so they omit this control.
85
+
86
+ The server also stops after 24 hours without a page or source request.
87
+ Loading or refreshing the page resets the timer; background health checks and
88
+ the live-reload connection do not keep it alive.
89
+
90
+ Check a spec without starting a server or publishing anything:
91
+
92
+ ```sh
93
+ npx product-doc validate .diffmap/specs/<name>/
94
+ ```
95
+
96
+ `validate` uses the viewer's parser to check every page's Markdown, diagrams, and
97
+ annotations, and the spec's page names. It exits 0 with `valid: true` and the
98
+ pages in order on success, and 1 with the error, naming the page, on failure.
99
+ Use `--json` for machine-readable output. It does not resolve source files or
100
+ Git commits. Run it after edits, including when reusing an already-running viewer.
101
+ After updating productdoc itself, restart existing viewers so they use the new parser.
102
+
103
+ List every running viewer, including viewers using custom ports:
104
+
105
+ ```sh
106
+ npx product-doc list
107
+ ```
108
+
109
+ Update a global install to the latest `product-doc` on npm. `product-doc --update` does the same thing:
110
+
111
+ ```sh
112
+ product-doc update
113
+ ```
114
+
115
+ If you are already on the latest version, it says so and exits. Otherwise it runs the global install for the package manager that installed productdoc (`npm install --global`, `pnpm add --global`, or `bun add --global`) and prints the old and new versions. Under `npx`, or when it cannot tell how productdoc was installed, it prints the command to run instead of installing anything.
116
+
117
+ Request a page with `Accept: text/markdown` to read its current source file
118
+ instead of the rendered HTML. Use the URL printed by `serve`, with the page's
119
+ slug for any page but the cover:
120
+
121
+ ```sh
122
+ curl -H 'Accept: text/markdown' http://127.0.0.1:<port>/write-through
123
+ ```
124
+
125
+ ## Spec layout
126
+
127
+ A spec is a directory of Markdown pages:
128
+
129
+ ```text
130
+ .diffmap/specs/sessions-in-postgres/
131
+ README.md the cover, at /
132
+ 01-sessions-table.md at /sessions-table
133
+ 02-write-through.md at /write-through
134
+ media/ images and videos the pages show
135
+ ```
136
+
137
+ - `README.md` is the cover. Its first `#` heading is the spec's title.
138
+ - Every other `.md` or `.mdx` file needs a number prefix, which sets its place:
139
+ `2-` comes before `10-`. The rest of the name, the slug, is the page's URL,
140
+ so renumbering pages keeps their links and comments. Two pages cannot share a
141
+ slug, and `validate` and `serve` reject a page without a number.
142
+ - The viewer shows one page at a time, with the spec's pages and the current
143
+ page's headings in the left gutter, and links to the previous and next page
144
+ at the bottom. A page's first heading is its title in that list.
145
+ - A relative link to a page file, such as `[Phase 2](02-write-through.md#tests)`,
146
+ opens that page, in productdoc and on GitHub.
147
+ - Each page keeps its own comments and Diff panel, which opens the page's first
148
+ `changes` card. **Copy comments** copies the comments from every page,
149
+ under each page's title.
150
+ - `serve` reloads a page when its file changes, and every page when you add,
151
+ remove, or retitle one.
152
+
153
+ Run `npx product-doc fixtures/sessions-in-postgres` for an example.
154
+
155
+ ## Share a spec with a link (experimental)
156
+
157
+ Share an unlisted gist and print a `diffmap.dev` link (requires [`gh`](https://cli.github.com/) logged in). Does not start a local server:
158
+
159
+ ```sh
160
+ npx product-doc share .diffmap/specs/<name>/
161
+ ```
162
+
163
+ A spec's pages share one gist. Hosted viewer: `https://diffmap.dev/g/<gistId>` for the cover, and `/<slug>` after it for a page (`#heading` is the table of contents). Gists shared before specs were directories still open, one file at a time. The page fetches the gist in the browser from `api.github.com`. Gists are unlisted, not private.
164
+
165
+ A spec committed to a GitHub pull request also opens at `https://diffmap.dev/<owner>/<repo>/pull/<n>/.diffmap/specs/<name>`, which pins to the pull request's head commit and opens the spec's cover. Its pages keep their file names in the URL, as in `…/commit/<sha>/.diffmap/specs/<name>/02-write-through.md`, since a pinned commit never renames them.
166
+
167
+ ## Library
168
+
169
+ ```ts
170
+ import { startServer, parseFence, parseViewerDocument } from "product-doc";
171
+ ```
172
+
173
+ `parseViewerDocument` turns markdown into the page document with [md4x](https://github.com/unjs/md4x). `startServer` listens. The guide that `product-doc guide` prints owns document shape; the viewer does not.
174
+
175
+ ## Fences
176
+
177
+ | Fence info string | Viewer |
178
+ | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
179
+ | `mermaid` | Beautiful Mermaid |
180
+ | `services` | Animated service diagram you can play or step through |
181
+ | `mermaid diff` or `services diff` | The same diagram with [added and removed parts marked](#diagram-diffs) |
182
+ | `callstack` or `diff` containing `└──` / `├──` | Interactive stack rows, no file header |
183
+ | `diff` or `diff:path` with a file path | Pierre patch with Pierre’s file header |
184
+ | `diff` with no path | Pierre patch, no file header |
185
+ | `changes` with a commit, range, or empty body | Files changed card with a Review button; empty means uncommitted changes |
186
+ | `start:end:path` | Pierre file excerpt with Pierre’s file header |
187
+ | `html` | Trusted HTML from this file. productdoc does not sanitize it. Only use it for local files you wrote. |
188
+ | other langs | Highlighted code with optional [titles, highlights, and notes](#highlight-lines-and-add-notes) |
189
+
190
+ Fences keep whitespace. Use them for mermaid, call stacks, and diffs.
191
+
192
+ ### Highlight lines and add notes
193
+
194
+ In a code fence, `{2,4-6}` after the language highlights those lines. Comment
195
+ lines at the bottom of the fence add notes that show on hover or keyboard focus:
196
+
197
+ ````md
198
+ ```ts {2-3}
199
+ function requestHandler(record: RecordInput) {
200
+ const error = validateInput(record);
201
+ if (error) return error;
202
+ return existingService(record);
203
+ }
204
+ // [!note L2 validateInput] Returns an error when `name` is blank, otherwise undefined.
205
+ // [!note L3] Early return, so storage never sees an invalid record.
206
+ ```
207
+ ````
208
+
209
+ - `[!note L3]` or `[!note L3-L5]` notes a line range, shown as a blue snippet highlight.
210
+ - `[!note L3 save]` or `[!note L3-L5 save]` notes the first whole-word
211
+ occurrence of `save` on each specified line, shown with a dotted underline.
212
+ - `[!note save]` applies fence-wide, matching the first whole-word occurrence
213
+ on each line. A scoped note takes precedence over a fence-wide note for the
214
+ same match. Matching is textual, not semantic symbol resolution.
215
+ - Start note lines with `//`, `#`, or `--`. The viewer removes them, so line
216
+ numbers count only the code above. Backticks in a note render as code.
217
+ - A symbol that does not appear within its scope, overlapping line notes, or a line number
218
+ outside the fence is a parse error. A note line above other code stays code.
219
+
220
+ Add `[Title]` after the language to show a title above the code, as in
221
+ ` ```ts [src/request.ts] {2-3} `. Call stacks and `mermaid` fences take a
222
+ title the same way, as in ` ```mermaid diff [Request flow] `, or
223
+ `::callstack{title="Request flow"}` and `::mermaid{title="Request flow"}` in
224
+ MDC. A `services` fence uses its [start caption](#animated-service-diagrams)
225
+ instead.
226
+
227
+ Call stacks take the same highlights and notes, counting rows from the first.
228
+ Write their notes with `#`. A symbol note matches the row text you see, not
229
+ hidden references. Inside a linked row, symbol notes show on hover only; the
230
+ row itself keeps keyboard focus.
231
+
232
+ Run `npx product-doc fixtures/code-notes` for an example.
233
+
234
+ ## MDC
235
+
236
+ md4x Comark components map to the same views:
237
+
238
+ ```md
239
+ ::mermaid
240
+ flowchart TD
241
+ A --> B
242
+ ::
243
+
244
+ ::callstack
245
+ startServer
246
+ +└── createViteServer
247
+ ::
248
+
249
+ ::diff{path="src/cli.ts"}
250
+ --- a/src/cli.ts
251
+ +++ b/src/cli.ts
252
+ ::
253
+
254
+ ::file{path="src/cli.ts" start="1" end="20"}
255
+ ::
256
+
257
+ ::changes{rev="a1b2c3d"}
258
+ ::
259
+
260
+ ::html
261
+ <aside>Note.</aside>
262
+ ::
263
+
264
+ ::details{summary="How it works"}
265
+ Folded content: prose, lists, and any fence above.
266
+ ::
267
+ ```
268
+
269
+ `::details` folds its content under the `summary` label until the reader opens it.
270
+ `.md` and `.mdx` are both markdown. Curly braces in prose are plain text.
271
+
272
+ ## Images, videos, and galleries
273
+
274
+ Show screenshots and recordings with Markdown image syntax. Paths are relative
275
+ to the spec file.
276
+
277
+ ```md
278
+ ![The save button after the fix](media/save.png)
279
+ ![Saving a record](media/save.mp4)
280
+ ```
281
+
282
+ A `.mp4`, `.webm`, `.mov`, `.m4v`, or `.ogv` file renders as a video player;
283
+ anything else is an image. On its own line, it shows centered in a card, with
284
+ its alt text as the title row. A title, as in `![alt](path "title")`, shows on
285
+ hover.
286
+
287
+ Group related images and videos in a gallery, with the layout after `:::gallery`:
288
+
289
+ ```md
290
+ :::gallery side-by-side
291
+ ![Before](media/before.png)
292
+ ![After](media/after.png)
293
+ :::
294
+ ```
295
+
296
+ - `side-by-side` puts every item in one row, to compare before and after or one
297
+ page at several widths.
298
+ - `grid` wraps items into rows, to scan states or variants.
299
+ - `carousel` shows one item at a time with Previous and Next (← and →), to step
300
+ through a flow. Add a title after the layout, as in
301
+ `:::gallery carousel [Saving a record]`; it stays in the title row while the
302
+ current item's label changes below it.
303
+
304
+ Each item's alt text is its visible label. A gallery holds only images and
305
+ videos, and `::gallery{layout="grid"}` works too. The syntax matches galleries
306
+ in Amp threads.
307
+
308
+ `serve` loads media from beside the spec, and a spec on a GitHub pull request
309
+ loads it from the same commit. `share` fails when a spec uses local media,
310
+ because a gist holds only text files; link media by https URL to share it.
311
+
312
+ Run `npx product-doc fixtures/media` for an example.
313
+
314
+ ## Link call stacks to source changes
315
+
316
+ Append a reference to a call stack line to link it. Paths are relative to `--root`.
317
+
318
+ - `[[path/to/file.ts#symbolName]]` links a TypeScript or JavaScript declaration,
319
+ including qualified names such as `[[src/store.ts#Store.save]]`. Ambiguous
320
+ names show the qualified names you can use instead.
321
+ - `[[path/to/file]]` links a whole file and `[[path/to/file#L12-L30]]` a line
322
+ range. These work with any language.
323
+ - `[[<sha>:path/to/file#L12-L30]]` or `[[<sha>:path/to/file]]` links a change
324
+ or an unchanged file in a commit. `<sha>` is a 7–40 character lowercase
325
+ commit SHA, or a range `<sha>..<sha>`.
326
+
327
+ ```callstack
328
+ shareMarkdownFile [[src/share.ts#shareMarkdownFile]]
329
+ +└── gistViewerUrl # print the diffmap.dev link [[d14ae1a:src/share.ts#L55-L59]]
330
+ ```
331
+
332
+ A reference without a commit opens the Diff panel on uncommitted changes
333
+ (working tree against HEAD), focused on that file or range. If the file has no
334
+ uncommitted changes, the panel shows the current file.
335
+
336
+ A commit reference opens the Diff panel on every file changed in that commit or
337
+ range, with a sticky header per file, scrolled to the linked file and lines.
338
+ Line numbers are the file's lines after the commit. If the file is unchanged,
339
+ the panel shows its source at that commit (or the destination of a range),
340
+ not the working tree. The file must exist there and the range must fit;
341
+ `serve` and `share` run git and fail at startup otherwise. Deleted lines cannot
342
+ be referenced, and a commit cannot be combined with `#symbol`.
343
+
344
+ Multiple references on one stack line are allowed. The references are hidden in
345
+ the rendered stack, and linked rows support mouse clicks and keyboard activation.
346
+
347
+ A `changes` fence shows a commit's files as a card. Each row shows the file name
348
+ and +N −M. **Review** opens the Diff panel on all files; a row scrolls to that
349
+ file without expanding its unchanged lines.
350
+ An empty body (or `working`) means uncommitted changes.
351
+
352
+ Lines after the rev list the files to review, in order. The card shows those
353
+ first and folds the rest under a dimmed **N other files** row that expands and
354
+ collapses. Review opens the Diff panel in the same order. With no list, the card
355
+ shows every file.
356
+
357
+ List files a reviewer can skip after an `ignore:` line. They fold away with the
358
+ rest; with nothing to review, the card says no files are marked as important. When a commit's fence lists files, `serve` prints a warning naming each
359
+ changed file that is in neither list, so no file is left out by accident.
360
+ `serve` and `share` fail if a listed file is not changed in that commit.
361
+
362
+ ````md
363
+ ```changes
364
+ a1b2c3d
365
+ src/request.ts
366
+ src/validate.ts
367
+
368
+ ignore:
369
+ package-lock.json
370
+ ```
371
+ ````
372
+
373
+ References open in one shared panel beside the walkthrough. Selecting a stack
374
+ line or diagram element highlights it and scrolls the panel to the linked code
375
+ range. When a target has several references, buttons above the source viewer
376
+ select among them. On narrow windows the source panel sits below the walkthrough.
377
+ Documents without references keep the single-panel layout.
378
+
379
+ Malformed references produce a parse error.
380
+
381
+ On a GitHub-hosted spec, commit diffs come from the GitHub API. It returns patch
382
+ hunks only, so only lines near changes are reachable, and the Diff button opens
383
+ the pull request's full diff.
384
+
385
+ A shared gist is a snapshot taken when you run `product-doc share`. It saves every
386
+ referenced commit and every `changes` card, including uncommitted ones, to
387
+ `diffmap-changes.json`, with unchanged supporting files saved at each referenced
388
+ revision separately from the changed-file list. It saves the current contents
389
+ of every file that a file excerpt or a reference without a commit reads to
390
+ `diffmap-files.json`. In the gist, references without a commit open that saved
391
+ file; symbols resolve to their first matching line, and Cmd-click definitions
392
+ only work in a local viewer. Commit
393
+ your work and point references at the commit before sharing, so the gist shows
394
+ the diff instead of a bare file.
395
+
396
+ Cmd-click (or Ctrl-click) a TypeScript or JavaScript symbol in the source panel
397
+ to open its definition. Use Back to retrace navigation and return to the reference.
398
+ Resolution uses the workspace's TypeScript configuration and current files.
399
+
400
+ Run `npx product-doc fixtures/annotations` for an example
401
+ with commit references, multiple files, and unchanged context.
402
+
403
+ ## Animated service diagrams
404
+
405
+ A `services` fence shows services, their state, and the events they send each
406
+ other, then replays those events step by step. Readers press **Play**, step with
407
+ the arrow buttons or ← and →, or click the progress bar to jump to a step.
408
+
409
+ ````md
410
+ ```services
411
+ service Browser "login page"
412
+ state cookie = none
413
+ service API "HTTP server" [[src/api.ts]]
414
+ > Receives every request and routes it to a service.
415
+ service Auth
416
+ state attempts = 0
417
+ > Failures since the last success. Five locks the account.
418
+
419
+ start "Alice logs in"
420
+ > The API checks her password with Auth, then sets a session cookie.
421
+ step "The browser submits the form"
422
+ Browser -> API: POST /login
423
+ step "The API asks Auth to verify"
424
+ API -> Auth: verify(alice) [[src/api.ts#login]]
425
+ > Sends the username and the password from the form.
426
+ Auth.attempts = 1
427
+ > Counted before the check, so a crash still counts as a failure.
428
+ step "The API sets the session cookie"
429
+ API -> Browser: 200 Set-Cookie
430
+ Browser.cookie = sid=s_81f
431
+ ```
432
+ ````
433
+
434
+ - `service <Name> "label"` declares a service. Indent a `service` line under
435
+ another to nest it. Names are unique within the diagram.
436
+ - `state <key> = <value>` declares a value and its initial state. Indent it under
437
+ its service.
438
+ - `start "caption"` at column 0, before the first step, titles the whole
439
+ diagram, such as `start "Alice logs in"`. It stays in the title row while the
440
+ reader steps. A `>` line under it gives an overview of the whole process,
441
+ shown under the title until the first step. A `services` fence takes no
442
+ `[Title]`; the start caption is its title.
443
+ - `step "caption"` starts a step at column 0. The caption is required: a
444
+ sentence that says what happens, shown under the title row above the
445
+ controls. Indented lines
446
+ under it are `From -> To: label` events and `Service.key = value` updates.
447
+ A step's events travel one after another, in the order written, and the
448
+ updates land when the last one arrives.
449
+ - A `>` line adds text to the line above it. Indent it further than that line;
450
+ consecutive `>` lines join.
451
+ - Under a service or state, it is a description: the name gets a dotted
452
+ underline and the text shows in a tooltip on hover or focus.
453
+ - Under `start` or a step, it explains the caption and shows under it.
454
+ - Under an event or update, it is a note for that step. Notes appear in a
455
+ column beside the diagram once the step's events land, each joined by a
456
+ line to its event label or state row.
457
+ - Under a service name on its own line in a step, it is a note on that
458
+ service for the step, joined by a line to the service box.
459
+ - `%%` starts a comment line.
460
+ - Append `[[reference]]` to a `service` line or an event to link it to source.
461
+
462
+ Services must be declared before the first step, and updates may only change
463
+ declared state. [ELK](https://eclipse.dev/elk/) lays the services out left to
464
+ right, or top to bottom when that fits the column better, and routes one
465
+ connection between each pair of services that talk. A request and its reply
466
+ share that connection. Indentation is significant, so `services` has no MDC form.
467
+ See [the runnable examples](fixtures/services/README.md).
468
+
469
+ ## Diagram diffs
470
+
471
+ Add `diff` after `mermaid` or `services` to show a change in one diagram.
472
+ Start every line with `-` for Today only, `+` for Proposed only, or a space
473
+ for both, as in a call stack diff. Indentation starts after that column.
474
+
475
+ ````md
476
+ ```mermaid diff
477
+ flowchart LR
478
+ Client --> Handler
479
+ - Handler --> Service
480
+ + Handler --> Validate
481
+ + Validate --> Service
482
+ ```
483
+ ````
484
+
485
+ productdoc draws every line once, so both versions share one layout. Nodes,
486
+ edges, sequence participants, and messages that only Today has are red and
487
+ dashed; those only Proposed has are green. A node whose label differs between
488
+ the versions is amber and shows its Proposed label. Each version must also be
489
+ a valid diagram on its own. To relabel a node, declare it on its own line
490
+ (`- B[Old]`, `+ B[New]`) so its edges are not drawn twice. In a diff,
491
+ `%% ref edge:<index>` counts edges as drawn: within each run of changed lines,
492
+ `+` lines come before `-` lines.
493
+
494
+ ````md
495
+ ```services diff
496
+ service API
497
+ - service SessionCache
498
+ - state active = 0
499
+ + service Sessions
500
+ service Postgres
501
+ - state sessions = not used
502
+ + state sessions = 0 rows
503
+
504
+ start "Sessions move to Postgres"
505
+ -step "API caches the session"
506
+ API -> SessionCache: create(alice)
507
+ SessionCache.active = 1
508
+ +step "Sessions writes the session"
509
+ API -> Sessions: create(alice)
510
+ Sessions -> Postgres: INSERT
511
+ Postgres.sessions = 1 row
512
+ ```
513
+ ````
514
+
515
+ In a `services diff`, lines inside a `-` or `+` service or step take its
516
+ sign. Today replays the unmarked and `-` lines and Proposed the unmarked and
517
+ `+` lines, so each state row shows Today's value struck through beside
518
+ Proposed's when they differ. A `-` and a `+` declaration of the same state key
519
+ give each version its own starting value. Added and removed steps color their
520
+ segment of the progress bar, and their caption starts with **Added** or
521
+ **Removed**. See [the runnable examples](fixtures/diagram-diffs/README.md).
522
+
523
+ ## Link Mermaid nodes and edges
524
+
525
+ Inside a Mermaid fence, add `%% ref node:<id> [[reference]]` to link a node or
526
+ participant, or `%% ref edge:<index> [[reference]]` to link an edge or sequence
527
+ message. Edge indices start at zero in declaration order. The same file, symbol,
528
+ and commit references work here. Keep one directive per target; append
529
+ multiple references to that directive when needed.
530
+
531
+ ````md
532
+ ```mermaid
533
+ flowchart LR
534
+ A[ViewerApp] -->|Local mode only| B[CloseServerButton]
535
+ %% ref node:A [[src/viewer/ViewerApp.tsx#ViewerApp]]
536
+ %% ref node:B [[dae6b98:src/viewer/CloseServerButton.tsx#L8-L16]]
537
+ %% ref edge:0 [[dae6b98:src/viewer/ViewerApp.tsx#L219-L227]]
538
+ ```
539
+
540
+ ```mermaid
541
+ sequenceDiagram
542
+ participant App
543
+ participant Store
544
+ App->>Store: Save record
545
+ %% ref node:Store [[src/store.ts#Store]]
546
+ %% ref edge:0 [[src/store.ts#Store.save]]
547
+ ```
548
+ ````
549
+
550
+ Click a linked shape, edge line, or edge label, or focus it with Tab and press
551
+ Enter or Space. Directives are Mermaid comments, so they remain hidden and do
552
+ not change the diagram when rendered by other Mermaid tools. Missing diagram
553
+ targets display an error. See [the runnable example](fixtures/references/README.md).
554
+
555
+ ## Link from prose
556
+
557
+ Write any reference in a paragraph, list item, or table cell, such as
558
+ `See [[src/store.ts#Store.save]] for the write path.` or
559
+ `Close server landed in [[dae6b98:src/viewer/CloseServerButton.tsx]].` It
560
+ renders as clickable inline code labeled with the file name and fragment
561
+ (`store.ts#Store.save`) and opens the same source panel. References inside code spans and link text stay
562
+ literal, so `` `[[path]]` `` shows the syntax itself.
563
+
564
+ ## Telemetry
565
+
566
+ The CLI sends anonymous usage events to [PostHog](https://posthog.com): which commands run, whether `serve` started, which coding agent ran it, and which features of the local viewer get used. Events never include file paths, spec contents, comments, or anything else from your repository. [TELEMETRY.md](TELEMETRY.md) lists every event and field.
567
+
568
+ Turn it off with `DIFFMAP_TELEMETRY=0` (or `false`) or `DO_NOT_TRACK=1`. It is also off when `CI` is set.
569
+
570
+ ## Feedback
571
+
572
+ Found a bug, hit a confusing error, or want a feature? Search [existing issues](https://github.com/tanishqkancharla/diffmap/issues), then comment on a matching issue or [open a new one](https://github.com/tanishqkancharla/diffmap/issues/new). Describe what you did, what you expected, and what happened, with your Productdoc version (`product-doc --version`). Keep submissions de-identified and prose-only, without PII, code, attachments, or identifying details.
573
+
574
+ Agents follow the [guide's Feedback section](guide.md#feedback) through `gh`, adding the `agent-feedback` label when available and the footer “Reported via Productdoc agent feedback” to issue bodies and comments. Diagnostic metadata is limited to the Productdoc version and agent product name, if known.
575
+
576
+ These markers identify the reporting path, not verified origin. This is guidance, not enforced anonymization: GitHub still shows the submitting account.
package/bin.js ADDED
@@ -0,0 +1,6 @@
1
+ #!/usr/bin/env node
2
+ import module from "node:module";
3
+
4
+ // Reuse V8's compiled code across runs (Node 22.1+), from the system temp directory.
5
+ module.enableCompileCache?.();
6
+ await import("./lib/cli.js");
@@ -0,0 +1,64 @@
1
+ # Live previews
2
+
3
+ A `preview` or `flow` block runs the app's real components in the spec, from the app's own Storybook stories. Use a `preview` block for a component or a design, with its variants side by side. Use a `flow` block for a journey of several states, or one that branches. Keep screenshots for UI that has no story, such as a whole page that needs a real backend.
4
+
5
+ ````text
6
+ ```preview [The log-in screen]
7
+ auth-log-in--empty
8
+ auth-log-in--wrong-password
9
+ ```
10
+
11
+ ```flow [Logging in]
12
+ auth-log-in--empty
13
+ auth-log-in--filled: Fill in email and password
14
+ auth-log-in--signed-in: Log in
15
+ auth-log-in--wrong-password: Log in with the wrong password
16
+ auth-log-in--forgot: Click "Forgot password?"
17
+ ```
18
+ ````
19
+
20
+ Name stories by their Storybook ID. In a `flow`, the first line is the starting state, and each later story is indented two spaces under the state it follows, with the action that leads to it after a colon. List the happy path first: the block's next-step button follows a state's first child.
21
+
22
+ **Set up the app once.** Skip this if the repo's `.diffmap/config.json` already has `previews`.
23
+
24
+ 1. If the app has no Storybook, add `@storybook/react` and `storybook` as dev dependencies; no Storybook server or config is needed. For screens that call the server, add `msw` and `msw-storybook-addon`, run `npx msw init public`, and add `mswLoader` to the preview's `loaders`.
25
+ 2. Add a page that the dev server and preview deployments serve, and the production deployment leaves out. In a Vite app, it is a `previews.html` beside `index.html`, added to `build.rollupOptions.input` only when the build is not for production, such as when `VERCEL_ENV` is not `production`. It loads:
26
+
27
+ ```tsx
28
+ import { createRoot } from "react-dom/client";
29
+ import { setProjectAnnotations } from "@storybook/react";
30
+ import { PreviewRoute } from "product-doc/preview";
31
+ import preview from "../../.storybook/preview";
32
+
33
+ setProjectAnnotations([preview]);
34
+ const stories = import.meta.glob("../**/*.stories.tsx", { eager: true });
35
+ createRoot(document.getElementById("root")!).render(
36
+ <PreviewRoute stories={stories} />,
37
+ );
38
+ ```
39
+
40
+ In a Next.js app, it is `app/__previews/page.tsx`, which calls `notFound()` on the production deployment, such as when `VERCEL_ENV` is `production`, and otherwise renders a client component with the same `PreviewRoute`, passing the story modules imported by hand. Import the project's `.storybook/preview` when it exists, so every story gets the app's decorators, providers, and global styles.
41
+
42
+ 3. Send `previewFrameAncestors`, from `product-doc/preview`, as the page's `Content-Security-Policy` header, so only the local viewer and diffmap.dev can frame it: from the dev server, as with Vite's `server.headers`, and from preview deployments, as with `headers` in `vercel.json` or `headers()` in `next.config`.
43
+ 4. Add the page's URLs to `.diffmap/config.json` at the repo root. `local` is the page on the dev server. `preview` is the page on each pull request's preview deployment, with `{branch}`, `{sha}`, or `{pull}`; diffmap.dev fills them from the pull request, with `{branch}` lowercase and every run of characters other than letters and digits turned into `-`, as Vercel and Netlify put a branch in a hostname. The deployment must be public, or diffmap.dev shows that it can't reach it.
44
+
45
+ ```json [.diffmap/config.json]
46
+ {
47
+ "previews": {
48
+ "local": "http://localhost:5173/previews.html",
49
+ "preview": "https://myapp-git-{branch}-myteam.vercel.app/previews.html"
50
+ }
51
+ }
52
+ ```
53
+
54
+ Add a `flows` key only to change a flow's defaults: `"transitions": "render"` draws each state from the start instead of playing the step on the live UI, and `"viewport": { "width": 1280, "height": 800 }` sets the size of the expanded flow.
55
+
56
+ **Write the stories.**
57
+
58
+ - Reuse the team's stories where they exist. Write new ones next to the component, in Storybook's format, with a `title`.
59
+ - Answer every request from the story's `parameters.msw.handlers`, never a live backend: previews must not sign anyone in, charge a card, or change real data. Use fixed values, not timestamps or random content.
60
+ - In a flow, each story after the first is one step from the story it is indented under. Its `play` does what the person does next, through `canvas` and `userEvent`, and its handlers give the server's answer to that step. Don't repeat the parent's steps: diffmap plays the path for you.
61
+ - Model events from outside the app, such as an email link or a provider's approval, as their own step with an action, not as buttons added to the UI.
62
+ - Write each story's `parameters.docs.description.story` as the state's note: what just happened, what is saved or still pending, and what the person can do next. Mark behavior that does not exist yet as proposed.
63
+
64
+ **Check before handing back.** With the app's dev server running, open each story on its own at `<previews.local>?story=<id>`, and each flow state at `?story=<id>&path=<ids from the start>`. Fix what the page lists as wrong with a story file. Then open the spec with `serve`, step through every state of each flow, and compare the states with the running app. The blocks show live UI only while the dev server runs; on a pull request, they load its preview deployment.