product-doc 0.13.2 → 0.14.2

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 (304) hide show
  1. package/README.md +31 -22
  2. package/guide/previews.md +68 -0
  3. package/guide/ui.md +13 -0
  4. package/guide.md +20 -17
  5. package/lib/changes.d.ts +4 -0
  6. package/lib/changes.js +5 -0
  7. package/lib/cli.js +99 -12
  8. package/lib/diffmapConfig.d.ts +41 -0
  9. package/lib/diffmapConfig.js +71 -0
  10. package/lib/git.d.ts +9 -4
  11. package/lib/git.js +42 -7
  12. package/lib/github/route.d.ts +1 -0
  13. package/lib/github/route.js +14 -5
  14. package/lib/parseFence.d.ts +30 -0
  15. package/lib/parseFence.js +62 -0
  16. package/lib/parseViewer.js +15 -0
  17. package/lib/preview/PreviewRoute.d.ts +20 -0
  18. package/lib/preview/PreviewRoute.js +279 -0
  19. package/lib/preview/index.d.ts +3 -0
  20. package/lib/preview/index.js +2 -0
  21. package/lib/preview/protocol.d.ts +85 -0
  22. package/lib/preview/protocol.js +114 -0
  23. package/lib/readDiffmapConfig.d.ts +12 -0
  24. package/lib/readDiffmapConfig.js +25 -0
  25. package/lib/serve.d.ts +2 -0
  26. package/lib/serve.js +41 -7
  27. package/lib/share.js +5 -1
  28. package/package.json +21 -4
  29. package/viewer-dist/assets/angular-html-C4LeXCe-.js +1 -0
  30. package/viewer-dist/assets/angular-ts-CRxW7p1W.js +1 -0
  31. package/viewer-dist/assets/{apl-Dio8Ke0X.js → apl-D60kkz--.js} +1 -1
  32. package/viewer-dist/assets/astro-3Zgg9XqN.js +1 -0
  33. package/viewer-dist/assets/{bat-HFWzIrao.js → bat-qdxAdBWQ.js} +1 -1
  34. package/viewer-dist/assets/{bibtex-Conh3HYz.js → bibtex-Ci_nEsc7.js} +1 -1
  35. package/viewer-dist/assets/blade-B5YUZNEG.js +1 -0
  36. package/viewer-dist/assets/bsl-_VjlB9mv.js +1 -0
  37. package/viewer-dist/assets/c-BNQJhXlP.js +1 -0
  38. package/viewer-dist/assets/cairo-DLTphjLi.js +1 -0
  39. package/viewer-dist/assets/{chapel-C1sUNn9S.js → chapel-CFMD-Djs.js} +1 -1
  40. package/viewer-dist/assets/{clojure-zIjcJonk.js → clojure-DqKBuwfJ.js} +1 -1
  41. package/viewer-dist/assets/{cmake-T_kMSWuN.js → cmake-Bj61d0ZC.js} +1 -1
  42. package/viewer-dist/assets/{cobol-BvqUwMCV.js → cobol-DY6IFdmX.js} +1 -1
  43. package/viewer-dist/assets/{coffee-BSYIIMkB.js → coffee-BP03ytLP.js} +1 -1
  44. package/viewer-dist/assets/{core-A38CGsfQ.js → core-cZCITU9I.js} +2 -2
  45. package/viewer-dist/assets/cpp-CUBNVKxn.js +1 -0
  46. package/viewer-dist/assets/{crystal-D0XIDmeW.js → crystal-NSr8mDkd.js} +1 -1
  47. package/viewer-dist/assets/{csharp-B3DbjJyj.js → csharp-dmMxLVLW.js} +1 -1
  48. package/viewer-dist/assets/css-BiJUKRHp.js +1 -0
  49. package/viewer-dist/assets/{csv-B_R7vXwK.js → csv-Dx-8-gkx.js} +1 -1
  50. package/viewer-dist/assets/{dart-_dH3dQdM.js → dart-CHZY9Xhz.js} +1 -1
  51. package/viewer-dist/assets/{diff-CR4ZX0DC.js → diff-woXpYk--.js} +1 -1
  52. package/viewer-dist/assets/{docker-CAzcIhYn.js → docker-IyjqRm3v.js} +1 -1
  53. package/viewer-dist/assets/edge-DznSXZdq.js +1 -0
  54. package/viewer-dist/assets/{elixir-BL8v4QDr.js → elixir-D1HcpP2u.js} +1 -1
  55. package/viewer-dist/assets/{elm-CC1TmzeR.js → elm-Bmx6Fs0i.js} +1 -1
  56. package/viewer-dist/assets/{erb-CHbMJpQy.js → erb-CdvLbCTI.js} +1 -1
  57. package/viewer-dist/assets/erlang-Cphh6RMH.js +1 -0
  58. package/viewer-dist/assets/fortran-fixed-form-DEKoE2YW.js +1 -0
  59. package/viewer-dist/assets/{fortran-free-form-uHOymLAb.js → fortran-free-form-CYNrtFtB.js} +1 -1
  60. package/viewer-dist/assets/fsharp-D13ZGOAj.js +1 -0
  61. package/viewer-dist/assets/gdresource-xMC7jr7x.js +1 -0
  62. package/viewer-dist/assets/{gdscript-DJFPOtzS.js → gdscript-DYvRD3hg.js} +1 -1
  63. package/viewer-dist/assets/{gdshader-kiBtQlv1.js → gdshader-CBce3t8t.js} +1 -1
  64. package/viewer-dist/assets/git-commit-BSykSTBG.js +1 -0
  65. package/viewer-dist/assets/{git-rebase-Bh7mDoAc.js → git-rebase-C-RR1FSc.js} +1 -1
  66. package/viewer-dist/assets/{glimmer-js-CIdbWayl.js → glimmer-js-BUse42ki.js} +1 -1
  67. package/viewer-dist/assets/{glimmer-ts-B16xCo2k.js → glimmer-ts-zH_nSjyx.js} +1 -1
  68. package/viewer-dist/assets/glsl-CyFpZtQv.js +1 -0
  69. package/viewer-dist/assets/{go-CFMhVTkq.js → go-rLFTqkRN.js} +1 -1
  70. package/viewer-dist/assets/graphql-BIyAKkG2.js +1 -0
  71. package/viewer-dist/assets/{groovy-Dj7WCBJM.js → groovy-CacY0gHj.js} +1 -1
  72. package/viewer-dist/assets/{hack-C30D-q0p.js → hack-qk6BiceN.js} +1 -1
  73. package/viewer-dist/assets/haml-BkBm6IgF.js +1 -0
  74. package/viewer-dist/assets/{handlebars-g-3gLrXt.js → handlebars-FMeV8O-Z.js} +1 -1
  75. package/viewer-dist/assets/{haxe-CD8O8Ul0.js → haxe-C8oCnwJJ.js} +1 -1
  76. package/viewer-dist/assets/{highlights-B57wCzB5.js → highlights-nN81K30Y.js} +2 -2
  77. package/viewer-dist/assets/{hlsl-ajL2FB-w.js → hlsl-Cvrh5tZx.js} +1 -1
  78. package/viewer-dist/assets/html-CvoVzlT3.js +1 -0
  79. package/viewer-dist/assets/{html-derivative-DyzJkWO6.js → html-derivative-CmO0_REm.js} +1 -1
  80. package/viewer-dist/assets/{http-BjrBtiM6.js → http-c4_vT9ST.js} +1 -1
  81. package/viewer-dist/assets/{hurl-B4P9s9G3.js → hurl-BqZA9I9Q.js} +1 -1
  82. package/viewer-dist/assets/hxml-Dcm88srW.js +1 -0
  83. package/viewer-dist/assets/index-DOfF35Q-.js +264 -0
  84. package/viewer-dist/assets/{ini-0B7NLFlx.js → ini-B5eOa1yu.js} +1 -1
  85. package/viewer-dist/assets/java-D7h0NA_A.js +1 -0
  86. package/viewer-dist/assets/javascript-DcMHgNcu.js +1 -0
  87. package/viewer-dist/assets/{jinja-dRcm23Ea.js → jinja-IxhZJXij.js} +1 -1
  88. package/viewer-dist/assets/{jison-D3aJooqo.js → jison-Ru_S5AEn.js} +1 -1
  89. package/viewer-dist/assets/json-DePJdKYk.js +1 -0
  90. package/viewer-dist/assets/{jsonc-dcnCvL0G.js → jsonc-CYpm1nAK.js} +1 -1
  91. package/viewer-dist/assets/jsx-BUUYi3qs.js +1 -0
  92. package/viewer-dist/assets/julia-BuaSHoYZ.js +1 -0
  93. package/viewer-dist/assets/just-BJW1YJYB.js +1 -0
  94. package/viewer-dist/assets/langs-b5pvyHTU.js +2 -0
  95. package/viewer-dist/assets/{latex-B_Ztlc7G.js → latex-B6yY1rfM.js} +1 -1
  96. package/viewer-dist/assets/{less-B64L-FWb.js → less-DVTAwKKz.js} +1 -1
  97. package/viewer-dist/assets/{liquid-CQNtsgCr.js → liquid-DNgNMjPq.js} +1 -1
  98. package/viewer-dist/assets/loader-DfKq13Mg.js +1 -0
  99. package/viewer-dist/assets/{log-BvtJ4bSl.js → log-BNLmms1o.js} +1 -1
  100. package/viewer-dist/assets/lua-Z49wBRLR.js +1 -0
  101. package/viewer-dist/assets/{make-URElk0GJ.js → make-Dixweg8N.js} +1 -1
  102. package/viewer-dist/assets/{markdown-CboqBxpY.js → markdown-BYOwaDjH.js} +1 -1
  103. package/viewer-dist/assets/marko-i5cBncq8.js +1 -0
  104. package/viewer-dist/assets/mdc-C3wRYKz5.js +1 -0
  105. package/viewer-dist/assets/nextflow-CSgcYZcx.js +1 -0
  106. package/viewer-dist/assets/{nextflow-groovy-C770ykRh.js → nextflow-groovy-D7IRt6Pp.js} +1 -1
  107. package/viewer-dist/assets/{nginx-BxRBJ-Af.js → nginx-BrbrEdla.js} +1 -1
  108. package/viewer-dist/assets/nim-BCe7ZKXY.js +1 -0
  109. package/viewer-dist/assets/{objective-c-D_ECFp-D.js → objective-c-D1A_Heim.js} +1 -1
  110. package/viewer-dist/assets/{ocaml-D6dNsUd0.js → ocaml-O90oeIOV.js} +1 -1
  111. package/viewer-dist/assets/org-DDCXkPsd.js +1 -0
  112. package/viewer-dist/assets/{perl-sgZsTtaf.js → perl-DLhC7S_Q.js} +1 -1
  113. package/viewer-dist/assets/{php-D9QpVhjP.js → php-CDzTReqR.js} +1 -1
  114. package/viewer-dist/assets/{postcss-D_Wz94rJ.js → postcss-BXeXVLqQ.js} +1 -1
  115. package/viewer-dist/assets/{powershell-CItYMEtV.js → powershell-QtSnmXcu.js} +1 -1
  116. package/viewer-dist/assets/{pug-nGRwXpob.js → pug-COoI2o4U.js} +1 -1
  117. package/viewer-dist/assets/{python-CzFU0dpx.js → python-gzcpVVnB.js} +1 -1
  118. package/viewer-dist/assets/{qml-BxleM7bJ.js → qml-g4UDed-8.js} +1 -1
  119. package/viewer-dist/assets/r-CvCSiWB_.js +1 -0
  120. package/viewer-dist/assets/{raku-BtFKomnU.js → raku-B3gFvitq.js} +1 -1
  121. package/viewer-dist/assets/{razor-UAq-8THt.js → razor-BRLDaw7i.js} +1 -1
  122. package/viewer-dist/assets/regexp-I2jnduhj.js +1 -0
  123. package/viewer-dist/assets/rst-BEQnCgL0.js +1 -0
  124. package/viewer-dist/assets/{ruby-B6sU6EpJ.js → ruby-COXzLN2W.js} +1 -1
  125. package/viewer-dist/assets/{rust-DBZE5Si3.js → rust-DpiIf5JO.js} +1 -1
  126. package/viewer-dist/assets/{sas-BowjnAvi.js → sas-Cr47JhdL.js} +1 -1
  127. package/viewer-dist/assets/{scala-o2NiCLJc.js → scala-BiFt_7mu.js} +1 -1
  128. package/viewer-dist/assets/scss-BuNb6cgZ.js +1 -0
  129. package/viewer-dist/assets/{sdbl-CpzYUp7e.js → sdbl-bTVj8UrX.js} +1 -1
  130. package/viewer-dist/assets/shaderlab-TOUzSsQk.js +1 -0
  131. package/viewer-dist/assets/shellscript-B51zB43X.js +1 -0
  132. package/viewer-dist/assets/{shellsession-DDrivR0a.js → shellsession-B-KBpmJs.js} +1 -1
  133. package/viewer-dist/assets/shiki-CqdI0RHM.js +2 -0
  134. package/viewer-dist/assets/{soy-CUUUw2U6.js → soy-B-X4e_cm.js} +1 -1
  135. package/viewer-dist/assets/sparql-D_iOobhT.js +1 -0
  136. package/viewer-dist/assets/sql-CrePkbX5.js +1 -0
  137. package/viewer-dist/assets/{stata-Dj4sbAEx.js → stata-LQMPNdRb.js} +1 -1
  138. package/viewer-dist/assets/{stream-tokenizer-a_hv0fYK.js → stream-tokenizer-D5CKTlAR.js} +2 -2
  139. package/viewer-dist/assets/{stylus-LiTfbrWi.js → stylus-B6D30XZt.js} +1 -1
  140. package/viewer-dist/assets/{surrealql-NoXzmj18.js → surrealql-DalIYx4r.js} +1 -1
  141. package/viewer-dist/assets/svelte-CutSaB0m.js +1 -0
  142. package/viewer-dist/assets/{swift-DQ24oLw9.js → swift-CyEgAFGc.js} +1 -1
  143. package/viewer-dist/assets/{system-verilog-Dp2k_mze.js → system-verilog-Dh5ihWbf.js} +1 -1
  144. package/viewer-dist/assets/templ-STIZV9cS.js +1 -0
  145. package/viewer-dist/assets/tex-JPaUWOrn.js +1 -0
  146. package/viewer-dist/assets/themes-DsXaTcpb.js +2 -0
  147. package/viewer-dist/assets/{ts-tags-DLz2GTd3.js → ts-tags-DugY2c1f.js} +1 -1
  148. package/viewer-dist/assets/tsx-DvWhG4dC.js +1 -0
  149. package/viewer-dist/assets/{turtle-CcN57yC0.js → turtle-ByJddavk.js} +1 -1
  150. package/viewer-dist/assets/twig-CAQ2meH1.js +1 -0
  151. package/viewer-dist/assets/typescript-BTGs5etX.js +1 -0
  152. package/viewer-dist/assets/typst-D2auzO0m.js +1 -0
  153. package/viewer-dist/assets/{vb-3nVziYZS.js → vb-DOwzaHZ0.js} +1 -1
  154. package/viewer-dist/assets/{verilog-kL8Dwv27.js → verilog-B2gwz-sJ.js} +1 -1
  155. package/viewer-dist/assets/vue-Bu9nv_eN.js +1 -0
  156. package/viewer-dist/assets/{vue-html-CGMs_6qn.js → vue-html-BXjKVtKk.js} +1 -1
  157. package/viewer-dist/assets/vue-vine-Ci2qndh_.js +1 -0
  158. package/viewer-dist/assets/xml-C01ajBW7.js +1 -0
  159. package/viewer-dist/assets/{xsl-Czhm44Ae.js → xsl-CCLNyvR3.js} +1 -1
  160. package/viewer-dist/assets/yaml-BWCS3NLV.js +1 -0
  161. package/viewer-dist/assets/{zig-B7sSDI6F.js → zig-CMLA9XwU.js} +1 -1
  162. package/viewer-dist/index.html +1 -7
  163. package/viewer-dist/assets/angular-html-BswFT_28.js +0 -1
  164. package/viewer-dist/assets/angular-html-Cwa-lTMy.js +0 -1
  165. package/viewer-dist/assets/angular-ts-DOMhGxLQ.js +0 -1
  166. package/viewer-dist/assets/appendItems-BRdTC5zu.js +0 -3
  167. package/viewer-dist/assets/astro-CN6YWUG3.js +0 -1
  168. package/viewer-dist/assets/bat-Di-EdOIU.js +0 -1
  169. package/viewer-dist/assets/bibtex-CimSBJhw.js +0 -1
  170. package/viewer-dist/assets/blade-BrDpNfUX.js +0 -1
  171. package/viewer-dist/assets/bsl-gRq8cI6V.js +0 -1
  172. package/viewer-dist/assets/c-DWGmR78Y.js +0 -1
  173. package/viewer-dist/assets/c-SSSlmE39.js +0 -1
  174. package/viewer-dist/assets/cairo-D66nqRlU.js +0 -1
  175. package/viewer-dist/assets/clojure-BrC3BItl.js +0 -1
  176. package/viewer-dist/assets/cmake-BRht3inD.js +0 -1
  177. package/viewer-dist/assets/coffee-drHG6SJT.js +0 -1
  178. package/viewer-dist/assets/constants-CmGPilXJ.js +0 -1
  179. package/viewer-dist/assets/core-B86SFyc0.js +0 -1
  180. package/viewer-dist/assets/cpp-BDT6bThX.js +0 -1
  181. package/viewer-dist/assets/cpp-CcLCVKG_.js +0 -1
  182. package/viewer-dist/assets/csharp-DtuFCOLR.js +0 -1
  183. package/viewer-dist/assets/css-BGIxQoYs.js +0 -1
  184. package/viewer-dist/assets/css-DUjzNfgv.js +0 -1
  185. package/viewer-dist/assets/csv-D6mwZ2PH.js +0 -1
  186. package/viewer-dist/assets/dart-B8JJT_EX.js +0 -1
  187. package/viewer-dist/assets/diff-B0S3HUPm.js +0 -1
  188. package/viewer-dist/assets/docker-B3DZKTds.js +0 -1
  189. package/viewer-dist/assets/edge-B_SBzXGF.js +0 -1
  190. package/viewer-dist/assets/elixir-B0EKSUNS.js +0 -1
  191. package/viewer-dist/assets/erlang-CCXss5H6.js +0 -1
  192. package/viewer-dist/assets/erlang-DAWODyxE.js +0 -1
  193. package/viewer-dist/assets/formatCSSVariablePrefix-KRh9vnZf.js +0 -1
  194. package/viewer-dist/assets/fortran-fixed-form-1cK5gXa1.js +0 -1
  195. package/viewer-dist/assets/fortran-free-form-9zh5t3u2.js +0 -1
  196. package/viewer-dist/assets/fsharp-C37UASp4.js +0 -1
  197. package/viewer-dist/assets/fsharp-D8ZPuVlk.js +0 -1
  198. package/viewer-dist/assets/gdresource-LxjHb83i.js +0 -1
  199. package/viewer-dist/assets/gdscript-C2iVvkL_.js +0 -1
  200. package/viewer-dist/assets/gdshader-BpaOOKdG.js +0 -1
  201. package/viewer-dist/assets/git-commit-BAuDFD-1.js +0 -1
  202. package/viewer-dist/assets/git-commit-rNeRxB9Y.js +0 -1
  203. package/viewer-dist/assets/git-rebase-Cpv8mbcu.js +0 -1
  204. package/viewer-dist/assets/glsl-CaPTrB3a.js +0 -1
  205. package/viewer-dist/assets/glsl-ThNHWs2E.js +0 -1
  206. package/viewer-dist/assets/go-BrE3Phef.js +0 -1
  207. package/viewer-dist/assets/graphql-DAzSVzvB.js +0 -1
  208. package/viewer-dist/assets/graphql-DEIChqxY.js +0 -1
  209. package/viewer-dist/assets/groovy-D_Q3n-An.js +0 -1
  210. package/viewer-dist/assets/haml-C1zHJAQt.js +0 -1
  211. package/viewer-dist/assets/haml-mwfMQlUs.js +0 -1
  212. package/viewer-dist/assets/handlebars-CEZndQNl.js +0 -1
  213. package/viewer-dist/assets/haxe-j5FdAS1V.js +0 -1
  214. package/viewer-dist/assets/hlsl-C3sg_olF.js +0 -1
  215. package/viewer-dist/assets/html-DSw1lh5G.js +0 -1
  216. package/viewer-dist/assets/html-WQKKblVZ.js +0 -1
  217. package/viewer-dist/assets/html-derivative-CjJKezcp.js +0 -1
  218. package/viewer-dist/assets/hxml-DPF7XkXa.js +0 -1
  219. package/viewer-dist/assets/index-CVKGwJkR.js +0 -255
  220. package/viewer-dist/assets/ini-DxURaTxO.js +0 -1
  221. package/viewer-dist/assets/java-BtIQNnN0.js +0 -1
  222. package/viewer-dist/assets/java-DxlWrXwe.js +0 -1
  223. package/viewer-dist/assets/javascript-BzbQS41l.js +0 -1
  224. package/viewer-dist/assets/javascript-Yelw-5ZN.js +0 -1
  225. package/viewer-dist/assets/json-B88Oqtu5.js +0 -1
  226. package/viewer-dist/assets/json-CaljABEy.js +0 -1
  227. package/viewer-dist/assets/jsonc-CTI_jrid.js +0 -1
  228. package/viewer-dist/assets/jsx-D3KKoC5L.js +0 -1
  229. package/viewer-dist/assets/jsx-hEbJ82HF.js +0 -1
  230. package/viewer-dist/assets/julia-BCOw4cyx.js +0 -1
  231. package/viewer-dist/assets/julia-hqywDEUR.js +0 -1
  232. package/viewer-dist/assets/just-Br47BmIC.js +0 -1
  233. package/viewer-dist/assets/langs-JgP7EaER.js +0 -2
  234. package/viewer-dist/assets/latex-Djh9Fg1h.js +0 -1
  235. package/viewer-dist/assets/less-GWsDhusf.js +0 -1
  236. package/viewer-dist/assets/lib-IuaA1a0_.js +0 -9
  237. package/viewer-dist/assets/loader-D4gJynmd.js +0 -1
  238. package/viewer-dist/assets/log-DSUv6hjM.js +0 -1
  239. package/viewer-dist/assets/lua-BJObVtAx.js +0 -1
  240. package/viewer-dist/assets/lua-DjuecEsk.js +0 -1
  241. package/viewer-dist/assets/make-BLT6fICl.js +0 -1
  242. package/viewer-dist/assets/markdown-Cla8Gbs6.js +0 -1
  243. package/viewer-dist/assets/marko-DPS0EkZ1.js +0 -1
  244. package/viewer-dist/assets/mdc-C6srEd4p.js +0 -1
  245. package/viewer-dist/assets/nextflow-groovy-1acFxZ7Y.js +0 -1
  246. package/viewer-dist/assets/nextflow-uA5IJerx.js +0 -1
  247. package/viewer-dist/assets/nim-Dr8hIC6Y.js +0 -1
  248. package/viewer-dist/assets/nim-ZjzS1dcU.js +0 -1
  249. package/viewer-dist/assets/objective-c-DMLMCfZd.js +0 -1
  250. package/viewer-dist/assets/ocaml-oSZO9LTw.js +0 -1
  251. package/viewer-dist/assets/org-B3Y3gBCc.js +0 -1
  252. package/viewer-dist/assets/perl-Di9CLCS0.js +0 -1
  253. package/viewer-dist/assets/php-DXPvgw5o.js +0 -1
  254. package/viewer-dist/assets/postcss-e3XvZOFQ.js +0 -1
  255. package/viewer-dist/assets/powershell-DyPZnz5v.js +0 -1
  256. package/viewer-dist/assets/preload-helper-BZ1Pz5am.js +0 -1
  257. package/viewer-dist/assets/pug-BlofpNpK.js +0 -1
  258. package/viewer-dist/assets/python-ORI17Sev.js +0 -1
  259. package/viewer-dist/assets/r-DWzjseEo.js +0 -1
  260. package/viewer-dist/assets/r-Dr1JUpHl.js +0 -1
  261. package/viewer-dist/assets/raku-B6hKIqfP.js +0 -1
  262. package/viewer-dist/assets/regexp-B4pBNbU3.js +0 -1
  263. package/viewer-dist/assets/regexp-BWpGejPw.js +0 -1
  264. package/viewer-dist/assets/rst-DT-C-5fA.js +0 -1
  265. package/viewer-dist/assets/ruby-BwIxDKXu.js +0 -1
  266. package/viewer-dist/assets/rust-tUOVui2B.js +0 -1
  267. package/viewer-dist/assets/scala-Dcd77NNm.js +0 -1
  268. package/viewer-dist/assets/scss-CWs8DVSa.js +0 -1
  269. package/viewer-dist/assets/scss-Dec6wfVg.js +0 -1
  270. package/viewer-dist/assets/sdbl-DFPhMlBm.js +0 -1
  271. package/viewer-dist/assets/shaderlab-DY7g_Ava.js +0 -1
  272. package/viewer-dist/assets/shellscript-BiGZg9Om.js +0 -1
  273. package/viewer-dist/assets/shellscript-CqHdAlCp.js +0 -1
  274. package/viewer-dist/assets/shiki-BYYByAlk.js +0 -2
  275. package/viewer-dist/assets/sparql-Dy5Sx-zJ.js +0 -1
  276. package/viewer-dist/assets/sql-BOsskAmu.js +0 -1
  277. package/viewer-dist/assets/sql-CNu3Or2W.js +0 -1
  278. package/viewer-dist/assets/stylus-BOYZFyl7.js +0 -1
  279. package/viewer-dist/assets/svelte-BaCIHHWd.js +0 -1
  280. package/viewer-dist/assets/swift-CpxeRS9H.js +0 -1
  281. package/viewer-dist/assets/system-verilog-CIGW6CHD.js +0 -1
  282. package/viewer-dist/assets/templ-BfgLc4ra.js +0 -1
  283. package/viewer-dist/assets/tex-C9L8xJex.js +0 -1
  284. package/viewer-dist/assets/tex-CeakZqzU.js +0 -1
  285. package/viewer-dist/assets/themes-DP0gt5jG.js +0 -2
  286. package/viewer-dist/assets/tsx-5f3ulCja.js +0 -1
  287. package/viewer-dist/assets/tsx-BOvsFOI6.js +0 -1
  288. package/viewer-dist/assets/turtle-B2uMLKuz.js +0 -1
  289. package/viewer-dist/assets/twig-BuizuR2K.js +0 -1
  290. package/viewer-dist/assets/twig-p9meEoSL.js +0 -1
  291. package/viewer-dist/assets/typescript-Utq2Cl8c.js +0 -1
  292. package/viewer-dist/assets/typescript-j_1H8WHN.js +0 -1
  293. package/viewer-dist/assets/typst-qZ7a-KdK.js +0 -1
  294. package/viewer-dist/assets/unwrapDefault-ByDmBtHB.js +0 -1
  295. package/viewer-dist/assets/vb-Dcr14nCw.js +0 -1
  296. package/viewer-dist/assets/verilog-DUw2aqD4.js +0 -1
  297. package/viewer-dist/assets/vue-qH43U_rv.js +0 -1
  298. package/viewer-dist/assets/vue-vine-6XI2pIvQ.js +0 -1
  299. package/viewer-dist/assets/xml-CoDIzWF0.js +0 -1
  300. package/viewer-dist/assets/xml-WY0zc4PG.js +0 -1
  301. package/viewer-dist/assets/xsl-ChYNfH-b.js +0 -1
  302. package/viewer-dist/assets/yaml-CxbubiML.js +0 -1
  303. package/viewer-dist/assets/yaml-DijMHRDA.js +0 -1
  304. package/viewer-dist/assets/zig-VWdiCTxG.js +0 -1
package/README.md CHANGED
@@ -6,29 +6,31 @@ Use it to explain an existing workflow, plan future work, or review a change. Do
6
6
 
7
7
  ## Try it
8
8
 
9
- **Release status:** the renamed package is prepared in this checkout, not yet published. The commands below describe the release candidate. From this checkout, use `npm run cli -- guide` or `npm run cli -- serve <directory>` until publication; do not expect a public npm install to work yet.
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
10
 
11
- Install the skill after the package is released:
11
+ From your project, ask your agent:
12
12
 
13
- ```sh
14
- npx skills add tanishqkancharla/diffmap --skill generate-product-doc
13
+ ```text
14
+ Install the generate-product-doc skill from tanishqkancharla/diffmap, then use it to explain how this project works.
15
15
  ```
16
16
 
17
- Then ask your agent to explain an existing system, plan work, or review changes:
17
+ Or install the skill yourself, selecting your coding agent when prompted:
18
18
 
19
- ```text
20
- Use generate-product-doc to explain how this app handles sign-in, including what happens when the session expires.
19
+ ```sh
20
+ npx skills add tanishqkancharla/diffmap --skill generate-product-doc
21
21
  ```
22
22
 
23
- The skill is a short pointer: your agent loads the full instructions from `npx product-doc guide`, so they stay version-matched to the viewer. When the stub itself changes, update it with `npx skills update generate-product-doc`.
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`.
24
26
 
25
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.
26
28
 
27
29
  ### Migrating from Diffmap
28
30
 
29
- 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 will be **productdoc.dev**. The GitHub repository keeps its current URL.
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.
30
32
 
31
- Both skills coexist temporarily. Existing published Diffmap packages, the legacy skill, and the live site are unchanged by these local edits; users will be invited to migrate later. Keep existing documents and paths rather than copying them. No legacy binary alias or automatic installation migration is added.
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.
32
34
 
33
35
  [The original Diffmap launch video](https://x.com/tanishqk/status/2116212881125691850) shows the review workflow this builds on.
34
36
 
@@ -160,7 +162,7 @@ npx product-doc share .diffmap/specs/<name>/
160
162
 
161
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.
162
164
 
163
- 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.
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.
164
166
 
165
167
  ## Library
166
168
 
@@ -319,8 +321,8 @@ Append a reference to a call stack line to link it. Paths are relative to `--roo
319
321
  - `[[path/to/file]]` links a whole file and `[[path/to/file#L12-L30]]` a line
320
322
  range. These work with any language.
321
323
  - `[[<sha>:path/to/file#L12-L30]]` or `[[<sha>:path/to/file]]` links a change
322
- in a commit. `<sha>` is a 7–40 character lowercase commit SHA, or a range
323
- `<sha>..<sha>`.
324
+ or an unchanged file in a commit. `<sha>` is a 7–40 character lowercase
325
+ commit SHA, or a range `<sha>..<sha>`.
324
326
 
325
327
  ```callstack
326
328
  shareMarkdownFile [[src/share.ts#shareMarkdownFile]]
@@ -333,10 +335,11 @@ uncommitted changes, the panel shows the current file.
333
335
 
334
336
  A commit reference opens the Diff panel on every file changed in that commit or
335
337
  range, with a sticky header per file, scrolled to the linked file and lines.
336
- Line numbers are the file's lines after the commit. The file must be changed in
337
- that commit and the range must fit the new file; `serve` and `share` run git and
338
- fail at startup otherwise. Deleted lines cannot be referenced, and a commit
339
- cannot be combined with `#symbol`.
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`.
340
343
 
341
344
  Multiple references on one stack line are allowed. The references are hidden in
342
345
  the rendered stack, and linked rows support mouse clicks and keyboard activation.
@@ -381,10 +384,12 @@ the pull request's full diff.
381
384
 
382
385
  A shared gist is a snapshot taken when you run `product-doc share`. It saves every
383
386
  referenced commit and every `changes` card, including uncommitted ones, to
384
- `diffmap-changes.json`. It saves the current contents of every file that a file
385
- excerpt or a reference without a commit reads to `diffmap-files.json`. In the
386
- gist, those references open the saved file; symbols resolve to their first
387
- matching line, and Cmd-click definitions only work in a local viewer. Commit
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
388
393
  your work and point references at the commit before sharing, so the gist shows
389
394
  the diff instead of a bare file.
390
395
 
@@ -564,4 +569,8 @@ Turn it off with `DIFFMAP_TELEMETRY=0` (or `false`) or `DO_NOT_TRACK=1`. It is a
564
569
 
565
570
  ## Feedback
566
571
 
567
- Found a bug, hit a confusing error, or want a feature? [Open an issue](https://github.com/tanishqkancharla/diffmap/issues/new) with what you did, what you expected, what happened, and your productdoc version (`product-doc --version`). Agents using the generate-product-doc skill do the same through `gh issue create`.
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.
@@ -0,0 +1,68 @@
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
+ **Choose the states from the real UI.** Read the component, the screens that use it, and how its state changes. Map where the person starts, what they do, and the success, loading, validation, failure, retry, and permission states that matter to the change. Don't invent screens to fill out a flow.
57
+
58
+ **Write the stories.**
59
+
60
+ - Reuse the team's stories where they exist. Write new ones next to the component, in Storybook's format, with a `title`.
61
+ - Render the real component, through its props and the story's fixtures. If it mixes server calls with rendering, propose pulling out a small presentational component; never keep a lookalike copy of the UI for previews.
62
+ - 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.
63
+ - 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.
64
+ - Reach each state through the controls a person uses: click the real buttons, type one keystroke at a time, open the real menu and pick its item. The app's own transitions, such as a menu opening or a validation message appearing, then play in the preview as they do in the app. Set state directly only when no control reaches it.
65
+ - 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.
66
+ - 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.
67
+
68
+ **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, in light and dark themes and at a narrow width. The blocks show live UI only while the dev server runs; on a pull request, they load its preview deployment.
package/guide/ui.md ADDED
@@ -0,0 +1,13 @@
1
+ # Capture UI changes
2
+
3
+ When a phase changes a UI that has Storybook stories, or could have them, show it live instead: run `npx product-doc guide previews`. Otherwise, capture the running app with the browser automation you have, such as Playwright or agent-browser, and add the captures to the phase. They let the reader judge the result without running it, and they test your work: before you add a capture, look at it with the expected result in mind, and fix what it shows wrong. Skip captures for changes nobody sees, such as a refactor or a backend fix with no visible effect.
4
+
5
+ - Use screenshots by default: they show how a state looks. Take one per state, variant, or window width the change affects, default first, such as empty, loading, error, hover, or a narrow window, and label each with the state it shows.
6
+ - Record a clip only for what screenshots cannot show: hover and click feedback, menus, focus, dragging, transitions, or timing. Move a real pointer through the whole interaction, past neighboring controls, and keep the clip under about 15 seconds.
7
+ - Show Today beside Proposed when the comparison is the point, in a `side-by-side` gallery. Capture Today from the unchanged code, such as the base commit in a worktree, not from a mockup. Use `grid` to scan several states or variants, and `carousel` to step through the stages of a flow.
8
+ - Keep only captures that help the reader decide something. Leave out intermediate attempts; when a fix changes the UI, replace the capture so only the final one remains.
9
+ - Crop screenshots to the part that changed, keep text readable, and leave out secrets and personal data.
10
+ - Save captures under `media/<phase-slug>/` in the spec and link them relative to the page, as in `media/write-through/save.png`. Prefer `.mp4` for recordings, since every browser plays it. Commit them with the spec so the pull request viewer shows them; ask the user before committing more than a few megabytes.
11
+ - Above each capture, say in a sentence what to look for. Readers comment by highlighting that sentence or a gallery label, and **Copy comments** brings their notes back to you.
12
+ - A capture shows what happened; it does not prove the behavior. Say which checks you ran.
13
+ - `share` fails on local media. To share a spec with captures, link them by https URL, or open the spec on its pull request.
package/guide.md CHANGED
@@ -37,7 +37,7 @@ npx product-doc share .diffmap/specs/<name>/ # only when asked; prints https:
37
37
 
38
38
  `validate` checks every page's syntax, diagrams, and annotations, and the spec's page names, without starting a server; it does not resolve source files or Git commits. Fix validation errors before handing back the viewer. After updating productdoc itself, restart existing viewers to load its new parser.
39
39
 
40
- Leave the server running and give the user the directory and URL. It reloads a page when you edit it, and the page list when you add, remove, or retitle a page. Inspect the rendered document's diagrams, prose previews, and media before handing it back. Before sharing, commit finished work and point its references at the commit, as in [When a phase is complete](#when-a-phase-is-complete): `share` saves each referenced commit's diff into the gist, but a reference without a commit only opens the file as it was when shared. A shared gist is unlisted: anyone with the URL can read it, including every file it snapshots. A spec on a pull request is also at `https://diffmap.dev/<owner>/<repo>/pull/<n>/.diffmap/specs/<name>/`, pinned to a commit.
40
+ Leave the server running and give the user the directory and URL. It reloads a page when you edit it, and the page list when you add, remove, or retitle a page. Inspect the rendered document's diagrams, prose previews, and media before handing it back. Before sharing, commit finished work and point its references at the commit, as in [When a phase is complete](#when-a-phase-is-complete): `share` saves each referenced commit's diff into the gist, but a reference without a commit only opens the file as it was when shared. A shared gist is unlisted: anyone with the URL can read it, including every file it snapshots. A spec on a pull request is also at `https://diffmap.dev/<owner>/<repo>/pull/<n>/.diffmap/specs/<name>`, pinned to a commit.
41
41
 
42
42
  ## Shape
43
43
 
@@ -81,7 +81,7 @@ Use `services` when the parts keep state, run at the same time, or fan out; use
81
81
 
82
82
  **Links.** Link existing source with [references](#source-references); write planned symbols as plain text.
83
83
 
84
- **Screenshots and recordings.** When a phase changes something a person sees, show it; [Capture UI changes](#capture-ui-changes) says which kind to use. Write `![label](path)`; a `.mp4` or `.webm` path renders as a video player. Group related captures in a `:::gallery side-by-side`, `grid`, or `carousel`, and title a carousel like `:::gallery carousel [Saving a record]`. Each item's alt text is its visible label, and a gallery holds only images and videos.
84
+ **Screenshots and recordings.** When a phase changes something a person sees, show it, live in a `preview` or `flow` block or in captures; `product-doc guide ui` says which to use. Write `![label](path)`; a `.mp4` or `.webm` path renders as a video player. Group related captures in a `:::gallery side-by-side`, `grid`, or `carousel`, and title a carousel like `:::gallery carousel [Saving a record]`. Each item's alt text is its visible label, and a gallery holds only images and videos.
85
85
 
86
86
  ```md
87
87
  :::gallery side-by-side
@@ -207,19 +207,9 @@ src/request.test.ts
207
207
  ```
208
208
  ````
209
209
 
210
- ## Capture UI changes
210
+ ## UI changes
211
211
 
212
- When a phase changes a UI, capture the running app with the browser automation you have, such as Playwright or agent-browser, and add the captures to the phase. They let the reader judge the result without running it, and they test your work: before you add a capture, look at it with the expected result in mind, and fix what it shows wrong. Skip captures for changes nobody sees, such as a refactor or a backend fix with no visible effect.
213
-
214
- - Use screenshots by default: they show how a state looks. Take one per state, variant, or window width the change affects, default first, such as empty, loading, error, hover, or a narrow window, and label each with the state it shows.
215
- - Record a clip only for what screenshots cannot show: hover and click feedback, menus, focus, dragging, transitions, or timing. Move a real pointer through the whole interaction, past neighboring controls, and keep the clip under about 15 seconds.
216
- - Show Today beside Proposed when the comparison is the point, in a `side-by-side` gallery. Capture Today from the unchanged code, such as the base commit in a worktree, not from a mockup. Use `grid` to scan several states or variants, and `carousel` to step through the stages of a flow.
217
- - Keep only captures that help the reader decide something. Leave out intermediate attempts; when a fix changes the UI, replace the capture so only the final one remains.
218
- - Crop screenshots to the part that changed, keep text readable, and leave out secrets and personal data.
219
- - Save captures under `media/<phase-slug>/` in the spec and link them relative to the page, as in `media/write-through/save.png`. Prefer `.mp4` for recordings, since every browser plays it. Commit them with the spec so the pull request viewer shows them; ask the user before committing more than a few megabytes.
220
- - Above each capture, say in a sentence what to look for. Readers comment by highlighting that sentence or a gallery label, and **Copy comments** brings their notes back to you.
221
- - A capture shows what happened; it does not prove the behavior. Say which checks you ran.
222
- - `share` fails on local media. To share a spec with captures, link them by https URL, or open the spec on its pull request.
212
+ When a phase changes a UI, run `npx product-doc guide ui` and follow what it prints: when to show the UI live, and how to take screenshots and recordings. To show it live, from the app's Storybook stories, run `npx product-doc guide previews`, which covers the `preview` and `flow` blocks and setting them up in the app.
223
213
 
224
214
  ## Source references
225
215
 
@@ -236,14 +226,27 @@ Fences: `mermaid` draws a diagram, `services` an animated diagram of services, t
236
226
 
237
227
  ## Feedback
238
228
 
239
- When productdoc gets in your way or the user has feedback on it, such as a rendering bug, a confusing error, a missing feature, or advice in this guide that did not work, open an issue on the existing GitHub repo. Search first, and comment on a matching issue instead of opening a duplicate:
229
+ When productdoc gets in your way or the user has feedback on it, such as a rendering bug, a confusing error, a missing feature, or advice in this guide that did not work, report it on the existing GitHub repo. Search first, and comment on a matching issue instead of opening a duplicate:
240
230
 
241
231
  ```sh
242
232
  gh issue list --repo tanishqkancharla/diffmap --search "<keywords>" --state all
243
- gh issue create --repo tanishqkancharla/diffmap --title "<short summary>" --body "<details>"
233
+ gh issue create --repo tanishqkancharla/diffmap --title "<summary>" --body "<details and footer>"
234
+ gh issue comment "<issue-number>" --repo tanishqkancharla/diffmap --body "<details and footer>"
244
235
  ```
245
236
 
246
- Say what you did, what you expected, and what happened, with the productdoc version (`npx product-doc --version`) and the smallest Markdown that shows the problem. Issues are public, so leave out private code, file contents, paths, and gist links unless the user agrees. Give the user the issue URL.
237
+ Describe what you did, what you expected, and what happened. Keep titles, issue bodies, and comments de-identified and prose-only: no PII, code or spec snippets, raw logs, screenshots, credentials, or identifying details (including private paths, repository/customer names, and links).
238
+
239
+ End agent-submitted issue bodies and comments with this footer. Include only the Productdoc version (`npx product-doc --version`) and agent product name as diagnostic metadata; omit the agent line if unknown:
240
+
241
+ ```text
242
+ Reported via Productdoc agent feedback
243
+ Productdoc version: <version>
244
+ Agent: <product name>
245
+ ```
246
+
247
+ Add `--label agent-feedback` when creating an issue if the label is available; otherwise keep the footer and submit without it. Ask before changing shared label configuration. These markers identify the reporting path, not verified origin.
248
+
249
+ This is guidance, not enforced anonymization: GitHub still shows the submitting account. Give the user the issue URL.
247
250
 
248
251
  ## Look up the rest
249
252
 
package/lib/changes.d.ts CHANGED
@@ -73,7 +73,11 @@ export type Changes = {
73
73
  /** GitHub listed only the first files; `url` has the rest. */
74
74
  truncated?: boolean;
75
75
  files: ChangedFile[];
76
+ /** Unchanged supporting files at this rev's destination, keyed by path. */
77
+ sources?: Record<string, string>;
76
78
  };
79
+ /** Spec metadata is not part of the code review; match directories, not substrings. */
80
+ export declare function summaryFiles(files: ChangedFile[]): ChangedFile[];
77
81
  /**
78
82
  * Splits files into the ones to review, in `review` order, and the rest in
79
83
  * their original order. Listing no files at all means every file is to be
package/lib/changes.js CHANGED
@@ -88,12 +88,17 @@ export function windowLabel(deltas, window) {
88
88
  const from = oldest.kind === "commit" ? oldest.parent.slice(0, 7) : deltaName(oldest);
89
89
  return `${from}…${deltaName(newest)}`;
90
90
  }
91
+ /** Spec metadata is not part of the code review; match directories, not substrings. */
92
+ export function summaryFiles(files) {
93
+ return files.filter((file) => !file.path.split("/").slice(0, -1).includes(".diffmap"));
94
+ }
91
95
  /**
92
96
  * Splits files into the ones to review, in `review` order, and the rest in
93
97
  * their original order. Listing no files at all means every file is to be
94
98
  * reviewed; listing only files to ignore means none is.
95
99
  */
96
100
  export function orderForReview(files, review, ignore = []) {
101
+ files = summaryFiles(files);
97
102
  if (review.length === 0 && ignore.length === 0)
98
103
  return { reviewed: files, other: [] };
99
104
  const reviewed = review.flatMap((path) => files.find((file) => file.path === path) ?? []);
package/lib/cli.js CHANGED
@@ -5,6 +5,7 @@ import { packageVersion } from "./packageVersion.js";
5
5
  import { listRunningDiffmaps } from "./registry.js";
6
6
  import { exitAfterTelemetry, track, trackCommand } from "./telemetry.js";
7
7
  import { detectInstallMethod, fetchLatestVersion, packageName, resolveUpdateArgv, runCommand, runUpdate, } from "./update.js";
8
+ const guideTopics = ["ui", "previews"];
8
9
  const serveArgs = z.object({
9
10
  file: z
10
11
  .string()
@@ -14,11 +15,16 @@ const serveOptions = z.object({
14
15
  port: z.coerce.number().optional().describe("Port (default: a free port)"),
15
16
  root: z.string().optional().describe("Workspace root for file excerpts"),
16
17
  });
17
- const serveOutput = z.object({
18
- url: z.string(),
19
- file: z.string(),
20
- warnings: z.array(z.string()).optional(),
21
- });
18
+ const serveOutput = z.union([
19
+ z
20
+ .string()
21
+ .describe("What serve prints unless --format or --json asks for data"),
22
+ z.object({
23
+ url: z.string(),
24
+ file: z.string(),
25
+ warnings: z.array(z.string()).optional(),
26
+ }),
27
+ ]);
22
28
  async function* runServe(c) {
23
29
  trackCommand("serve");
24
30
  // Loaded per command so `--version`, `list`, and `update` skip the server's dependencies.
@@ -46,7 +52,7 @@ async function* runServe(c) {
46
52
  track("serve_result", { ok: false, error: started.name });
47
53
  return c.error({
48
54
  code: "DIFFMAP",
49
- message: started.message,
55
+ message: `Failed to serve ${c.args.file}: ${started.message.replace(/^diffmap /, "")}`,
50
56
  });
51
57
  }
52
58
  // How many of each fence kind the spec uses across its pages (a kind it never uses is left out), to see which parts of the guide agents follow.
@@ -66,13 +72,27 @@ async function* runServe(c) {
66
72
  file: started.filePath,
67
73
  ...(started.warnings.length > 0 ? { warnings: started.warnings } : {}),
68
74
  };
69
- yield output;
75
+ if (c.formatExplicit)
76
+ yield output;
77
+ else {
78
+ const pages = started.documents.length;
79
+ const counts = [`${pages} page${pages === 1 ? "" : "s"}`];
80
+ if (started.warnings.length > 0)
81
+ counts.push(`${started.warnings.length} warning${started.warnings.length === 1 ? "" : "s"}`);
82
+ yield [
83
+ `Serving ${c.args.file} at ${started.url} (${counts.join(", ")})`,
84
+ ...started.warnings.map((warning) => `Warning: ${warning}`),
85
+ "Stop with Ctrl+C or Close server in the viewer.",
86
+ ].join("\n");
87
+ }
70
88
  await started.closed;
71
89
  return output;
72
90
  }
73
91
  const cli = Cli.create("product-doc", {
74
92
  description: "Explain systems, plan work, and review changes as visual documents",
75
93
  version: packageVersion,
94
+ // The curated authoring skill is installed separately, not generated from commands.
95
+ sync: false,
76
96
  args: serveArgs,
77
97
  options: serveOptions,
78
98
  output: serveOutput,
@@ -157,10 +177,18 @@ const cli = Cli.create("product-doc", {
157
177
  })
158
178
  .command("guide", {
159
179
  description: "Print the instructions agents follow to write a spec",
180
+ args: z.object({
181
+ topic: z
182
+ .enum(guideTopics)
183
+ .optional()
184
+ .describe("A part the main guide sends you to: ui (showing a UI change) or previews (live preview and flow blocks)"),
185
+ }),
160
186
  output: z.string(),
161
- run() {
187
+ run(c) {
162
188
  trackCommand("guide");
163
- return readFileSync(new URL("../guide.md", import.meta.url), "utf8");
189
+ return readFileSync(new URL(c.args.topic === undefined
190
+ ? "../guide.md"
191
+ : `../guide/${c.args.topic}.md`, import.meta.url), "utf8");
164
192
  },
165
193
  })
166
194
  .command("list", {
@@ -212,6 +240,65 @@ const cli = Cli.create("product-doc", {
212
240
  return c.ok(result);
213
241
  },
214
242
  });
215
- await cli.serve(resolveUpdateArgv(process.argv.slice(2)), {
216
- exit: exitAfterTelemetry,
217
- });
243
+ const argv = resolveUpdateArgv(process.argv.slice(2));
244
+ // Incur has no MCP opt-out. Block its entry points before dispatch; do not
245
+ // mistake an option value or a spec passed to `serve` for a command.
246
+ const valueOptions = new Set([
247
+ "--port",
248
+ "--root",
249
+ "--format",
250
+ "--filter-output",
251
+ "--token-limit",
252
+ "--token-offset",
253
+ ]);
254
+ let command;
255
+ for (let index = 0; index < argv.length; index++) {
256
+ const arg = argv[index];
257
+ if (arg === "--")
258
+ break;
259
+ if (valueOptions.has(arg)) {
260
+ index++;
261
+ continue;
262
+ }
263
+ if (arg.startsWith("-") || arg === "product-doc")
264
+ continue;
265
+ command = arg;
266
+ break;
267
+ }
268
+ if (argv.includes("--mcp") || command === "mcp") {
269
+ if (!process.env.COMPLETE) {
270
+ process.stderr.write("MCP is not supported by product-doc. Run product-doc --help.\n");
271
+ exitAfterTelemetry(1);
272
+ }
273
+ }
274
+ else {
275
+ await cli.serve(argv, {
276
+ exit: exitAfterTelemetry,
277
+ stdout(output) {
278
+ if (process.env.COMPLETE && argv.length > 0) {
279
+ // Keep Incur's shell-specific encoding and all non-MCP candidates.
280
+ if (process.env.COMPLETE === "nushell") {
281
+ output = JSON.stringify(JSON.parse(output).filter((candidate) => candidate.value !== "mcp"));
282
+ }
283
+ else {
284
+ const separator = process.env.COMPLETE === "bash" ? "\v" : "\n";
285
+ output = output
286
+ .split(separator)
287
+ .filter((candidate) => candidate !== "mcp\x01" && !/^mcp(?:[:\t]|$)/.test(candidate))
288
+ .join(separator);
289
+ }
290
+ }
291
+ else if (argv.includes("--help") ||
292
+ argv.includes("-h") ||
293
+ (argv.length === 0 && process.stdout.isTTY)) {
294
+ output = output.replace(/^ (?:mcp|--mcp)\s.*\n/gm, "");
295
+ }
296
+ else if (output.includes("COMMAND_NOT_FOUND") &&
297
+ output.includes("Did you mean 'mcp'?")) {
298
+ process.stderr.write(`Unknown command ${JSON.stringify(command)}. Run product-doc --help.\n`);
299
+ return;
300
+ }
301
+ process.stdout.write(output);
302
+ },
303
+ });
304
+ }
@@ -0,0 +1,41 @@
1
+ /** `.diffmap/config.json`: diffmap's one config file, found in the spec's directory or a parent of it. */
2
+ export type DiffmapConfig = {
3
+ /** Where the app's preview page lives; preview and flow blocks load it. */
4
+ previews?: {
5
+ local?: string;
6
+ /** A pull request's preview deployment, with {branch}, {sha}, and {pull}. */
7
+ preview?: string;
8
+ };
9
+ /** Settings only flow blocks use. */
10
+ flows?: {
11
+ /** "play" plays a step on the live UI; "render" draws each state from the start. */
12
+ transitions?: "play" | "render";
13
+ /** The size the expanded flow renders the app at. */
14
+ viewport?: {
15
+ width: number;
16
+ height: number;
17
+ };
18
+ };
19
+ };
20
+ /** What the viewer gets for the spec it shows: the config, or why it can't be read. */
21
+ export type ConfigLoad = {
22
+ config: DiffmapConfig;
23
+ } | {
24
+ error: string;
25
+ };
26
+ /** The `.diffmap/config.json` paths that apply to a spec in `specDir`, nearest first, relative to the same root. */
27
+ export declare function configCandidates(specDir: string): string[];
28
+ export declare function parseDiffmapConfig(text: string): DiffmapConfig;
29
+ /** The pull request a spec on diffmap.dev was opened from, which fills `previews.preview`. */
30
+ export type DeploymentTarget = {
31
+ sha: string;
32
+ /** The pull request's head branch. */
33
+ branch?: string;
34
+ pull?: number;
35
+ };
36
+ /**
37
+ * `previews.preview` with its placeholders filled. `{branch}` is the branch
38
+ * name as Vercel and Netlify put it in a hostname: lowercase, with every run of
39
+ * characters other than letters and digits turned into `-`.
40
+ */
41
+ export declare function deploymentUrl(template: string, target: DeploymentTarget): string | Error;
@@ -0,0 +1,71 @@
1
+ /** The `.diffmap/config.json` paths that apply to a spec in `specDir`, nearest first, relative to the same root. */
2
+ export function configCandidates(specDir) {
3
+ const parts = specDir.split("/").filter((part) => part !== "");
4
+ return parts
5
+ .map((_, index) => parts.slice(0, parts.length - index).join("/"))
6
+ .concat("")
7
+ .map((dir) => (dir === "" ? "" : `${dir}/`) + ".diffmap/config.json");
8
+ }
9
+ export function parseDiffmapConfig(text) {
10
+ return checkConfig(JSON.parse(text));
11
+ }
12
+ function checkConfig(value) {
13
+ if (!isObject(value))
14
+ throw new Error("the file is not a JSON object");
15
+ const { previews, flows } = value;
16
+ if (previews !== undefined) {
17
+ if (!isObject(previews))
18
+ throw new Error("previews is an object with local and preview URLs");
19
+ for (const key of ["local", "preview"])
20
+ if (previews[key] !== undefined && typeof previews[key] !== "string")
21
+ throw new Error(`previews.${key} is a URL string`);
22
+ }
23
+ if (flows !== undefined) {
24
+ if (!isObject(flows))
25
+ throw new Error("flows is an object of settings");
26
+ if (flows.transitions !== undefined &&
27
+ flows.transitions !== "play" &&
28
+ flows.transitions !== "render")
29
+ throw new Error('flows.transitions is "play" or "render"');
30
+ const viewport = flows.viewport;
31
+ if (viewport !== undefined &&
32
+ !(isObject(viewport) &&
33
+ typeof viewport.width === "number" &&
34
+ typeof viewport.height === "number"))
35
+ throw new Error("flows.viewport is { width, height } in pixels");
36
+ }
37
+ // SAFETY: checked field by field above.
38
+ return value;
39
+ }
40
+ /**
41
+ * `previews.preview` with its placeholders filled. `{branch}` is the branch
42
+ * name as Vercel and Netlify put it in a hostname: lowercase, with every run of
43
+ * characters other than letters and digits turned into `-`.
44
+ */
45
+ export function deploymentUrl(template, target) {
46
+ const values = {
47
+ sha: target.sha,
48
+ branch: target.branch === undefined
49
+ ? undefined
50
+ : target.branch
51
+ .toLowerCase()
52
+ .replace(/[^a-z0-9]+/g, "-")
53
+ .replace(/^-|-$/g, ""),
54
+ pull: target.pull === undefined ? undefined : String(target.pull),
55
+ };
56
+ const missing = new Set();
57
+ const url = template.replace(/\{(sha|branch|pull)\}/g, (_, name) => {
58
+ const value = values[name];
59
+ if (value === undefined) {
60
+ missing.add(name);
61
+ return "";
62
+ }
63
+ return encodeURIComponent(value);
64
+ });
65
+ if (missing.size > 0)
66
+ return new Error(`previews.preview needs ${[...missing].map((name) => `{${name}}`).join(" and ")}, which come from the pull request.`);
67
+ return url;
68
+ }
69
+ function isObject(value) {
70
+ return typeof value === "object" && value !== null && !Array.isArray(value);
71
+ }
package/lib/git.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { type Delta, type Changes, type Rev } from "./changes.js";
2
2
  import { DiffmapGitError } from "./errors.js";
3
3
  import type { ChangeCard, ViewerDocument } from "./parseViewer.js";
4
+ import type { SourceDefinition } from "./definitions.js";
4
5
  /** Reads the files changed by a rev, with full old and new contents. */
5
6
  export declare function readChanges(root: string, rev: Rev): Promise<Changes | DiffmapGitError>;
6
7
  type NumstatEntry = {
@@ -20,10 +21,14 @@ export declare function parseNumstat(output: string): NumstatEntry[];
20
21
  export declare function listDeltas(root: string,
21
22
  /** The open rev; the list reaches back far enough to show it. */
22
23
  include?: Rev): Promise<Delta[] | DiffmapGitError>;
23
- /**
24
- * Loads every commit rev a document uses and checks that each commit
25
- * reference names a changed file and a range inside its new version.
26
- */
24
+ /** Read a text file at a commit (or a commit range's destination), never the worktree. */
25
+ export declare function readSnapshotReference(root: string, reference: {
26
+ rev: string;
27
+ path: string;
28
+ start?: number;
29
+ end?: number;
30
+ }): Promise<SourceDefinition | DiffmapGitError>;
31
+ /** Load commit diffs and snapshot any unchanged supporting references. */
27
32
  export declare function readDocumentChanges(root: string, document: Pick<ViewerDocument, "references" | "changeCards">): Promise<Map<Rev, Changes> | DiffmapGitError>;
28
33
  /**
29
34
  * One warning per commit `changes` card that lists files but leaves some