obsidian-plugin-dev-kit 0.0.0-stage → 0.3.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 (329) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +223 -2
  3. package/bin/opdk.js +34 -0
  4. package/dist/build/args.d.ts +10 -0
  5. package/dist/build/args.js +45 -0
  6. package/dist/build/bundle-check.d.ts +17 -0
  7. package/dist/build/bundle-check.js +42 -0
  8. package/dist/build/bundle-file.d.ts +4 -0
  9. package/dist/build/bundle-file.js +29 -0
  10. package/dist/build/commands.d.ts +5 -0
  11. package/dist/build/commands.js +109 -0
  12. package/dist/build/config.d.ts +3 -0
  13. package/dist/build/config.js +103 -0
  14. package/dist/build/css-imports.d.ts +23 -0
  15. package/dist/build/css-imports.js +50 -0
  16. package/dist/build/css-step.d.ts +10 -0
  17. package/dist/build/css-step.js +27 -0
  18. package/dist/build/css.d.ts +24 -0
  19. package/dist/build/css.js +47 -0
  20. package/dist/build/options.d.ts +55 -0
  21. package/dist/build/options.js +70 -0
  22. package/dist/build/release.d.ts +5 -0
  23. package/dist/build/release.js +34 -0
  24. package/dist/build/report.d.ts +7 -0
  25. package/dist/build/report.js +16 -0
  26. package/dist/build/vault.d.ts +26 -0
  27. package/dist/build/vault.js +290 -0
  28. package/dist/build-info.json +1 -0
  29. package/dist/cli/argv.d.ts +14 -0
  30. package/dist/cli/argv.js +18 -0
  31. package/dist/cli/commands.d.ts +3 -0
  32. package/dist/cli/commands.js +7 -0
  33. package/dist/cli/main.d.ts +2 -0
  34. package/dist/cli/main.js +23 -0
  35. package/dist/cli/process-reporter.d.ts +5 -0
  36. package/dist/cli/process-reporter.js +15 -0
  37. package/dist/cli/registry.d.ts +4 -0
  38. package/dist/cli/registry.js +15 -0
  39. package/dist/cli/reporter.d.ts +53 -0
  40. package/dist/cli/reporter.js +100 -0
  41. package/dist/cli/run.d.ts +9 -0
  42. package/dist/cli/run.js +61 -0
  43. package/dist/cli/types.d.ts +27 -0
  44. package/dist/cli/types.js +1 -0
  45. package/dist/cli/version.d.ts +13 -0
  46. package/dist/cli/version.js +61 -0
  47. package/dist/config/define-config.d.ts +3 -0
  48. package/dist/config/define-config.js +4 -0
  49. package/dist/config/load-config.d.ts +6 -0
  50. package/dist/config/load-config.js +70 -0
  51. package/dist/config/manifest.d.ts +3 -0
  52. package/dist/config/manifest.js +72 -0
  53. package/dist/config/types.d.ts +146 -0
  54. package/dist/config/types.js +23 -0
  55. package/dist/demo/args.d.ts +4 -0
  56. package/dist/demo/args.js +13 -0
  57. package/dist/demo/checks.d.ts +56 -0
  58. package/dist/demo/checks.js +124 -0
  59. package/dist/demo/commands.d.ts +3 -0
  60. package/dist/demo/commands.js +65 -0
  61. package/dist/demo/config.d.ts +57 -0
  62. package/dist/demo/config.js +337 -0
  63. package/dist/demo/ffmpeg-run.d.ts +18 -0
  64. package/dist/demo/ffmpeg-run.js +59 -0
  65. package/dist/demo/ffmpeg.d.ts +63 -0
  66. package/dist/demo/ffmpeg.js +111 -0
  67. package/dist/demo/films.d.ts +46 -0
  68. package/dist/demo/films.js +134 -0
  69. package/dist/demo/phone-layout.d.ts +38 -0
  70. package/dist/demo/phone-layout.js +98 -0
  71. package/dist/demo/phone-render.d.ts +28 -0
  72. package/dist/demo/phone-render.js +124 -0
  73. package/dist/demo/published.d.ts +16 -0
  74. package/dist/demo/published.js +72 -0
  75. package/dist/demo/run.d.ts +31 -0
  76. package/dist/demo/run.js +397 -0
  77. package/dist/demo/stills.d.ts +21 -0
  78. package/dist/demo/stills.js +62 -0
  79. package/dist/e2e/artifacts.d.ts +27 -0
  80. package/dist/e2e/artifacts.js +90 -0
  81. package/dist/e2e/cleanup.d.ts +54 -0
  82. package/dist/e2e/cleanup.js +109 -0
  83. package/dist/e2e/config.d.ts +9 -0
  84. package/dist/e2e/config.js +42 -0
  85. package/dist/e2e/create-test.d.ts +37 -0
  86. package/dist/e2e/create-test.js +109 -0
  87. package/dist/e2e/demo/clip.d.ts +21 -0
  88. package/dist/e2e/demo/clip.js +44 -0
  89. package/dist/e2e/demo/create-demo.d.ts +42 -0
  90. package/dist/e2e/demo/create-demo.js +439 -0
  91. package/dist/e2e/demo/manifest.d.ts +76 -0
  92. package/dist/e2e/demo/manifest.js +168 -0
  93. package/dist/e2e/demo/names.d.ts +18 -0
  94. package/dist/e2e/demo/names.js +44 -0
  95. package/dist/e2e/demo/options.d.ts +22 -0
  96. package/dist/e2e/demo/options.js +59 -0
  97. package/dist/e2e/demo/ownership.d.ts +27 -0
  98. package/dist/e2e/demo/ownership.js +65 -0
  99. package/dist/e2e/demo/page-scripts.d.ts +82 -0
  100. package/dist/e2e/demo/page-scripts.js +250 -0
  101. package/dist/e2e/demo/png.d.ts +8 -0
  102. package/dist/e2e/demo/png.js +23 -0
  103. package/dist/e2e/demo/presets.d.ts +43 -0
  104. package/dist/e2e/demo/presets.js +20 -0
  105. package/dist/e2e/demo/privacy.d.ts +18 -0
  106. package/dist/e2e/demo/privacy.js +30 -0
  107. package/dist/e2e/demo/still-options.d.ts +22 -0
  108. package/dist/e2e/demo/still-options.js +68 -0
  109. package/dist/e2e/demo/types.d.ts +184 -0
  110. package/dist/e2e/demo/types.js +1 -0
  111. package/dist/e2e/electron-binary.d.ts +15 -0
  112. package/dist/e2e/electron-binary.js +30 -0
  113. package/dist/e2e/fixtures.d.ts +62 -0
  114. package/dist/e2e/fixtures.js +68 -0
  115. package/dist/e2e/gate.d.ts +4 -0
  116. package/dist/e2e/gate.js +8 -0
  117. package/dist/e2e/global-setup.d.ts +11 -0
  118. package/dist/e2e/global-setup.js +17 -0
  119. package/dist/e2e/helpers/commands.d.ts +14 -0
  120. package/dist/e2e/helpers/commands.js +56 -0
  121. package/dist/e2e/helpers/create-helpers.d.ts +24 -0
  122. package/dist/e2e/helpers/create-helpers.js +582 -0
  123. package/dist/e2e/helpers/device-metrics.d.ts +21 -0
  124. package/dist/e2e/helpers/device-metrics.js +25 -0
  125. package/dist/e2e/helpers/ime.d.ts +13 -0
  126. package/dist/e2e/helpers/ime.js +19 -0
  127. package/dist/e2e/helpers/layout-page-scripts.d.ts +103 -0
  128. package/dist/e2e/helpers/layout-page-scripts.js +224 -0
  129. package/dist/e2e/helpers/layout.d.ts +83 -0
  130. package/dist/e2e/helpers/layout.js +148 -0
  131. package/dist/e2e/helpers/mobile.d.ts +31 -0
  132. package/dist/e2e/helpers/mobile.js +26 -0
  133. package/dist/e2e/helpers/page-scripts.d.ts +194 -0
  134. package/dist/e2e/helpers/page-scripts.js +467 -0
  135. package/dist/e2e/helpers/settings.d.ts +8 -0
  136. package/dist/e2e/helpers/settings.js +16 -0
  137. package/dist/e2e/helpers/settle.d.ts +28 -0
  138. package/dist/e2e/helpers/settle.js +33 -0
  139. package/dist/e2e/helpers/types.d.ts +193 -0
  140. package/dist/e2e/helpers/types.js +1 -0
  141. package/dist/e2e/helpers/view-mode.d.ts +23 -0
  142. package/dist/e2e/helpers/view-mode.js +35 -0
  143. package/dist/e2e/index.d.ts +14 -0
  144. package/dist/e2e/index.js +4 -0
  145. package/dist/e2e/internals.d.ts +155 -0
  146. package/dist/e2e/internals.js +8 -0
  147. package/dist/e2e/obsidian-path.d.ts +17 -0
  148. package/dist/e2e/obsidian-path.js +31 -0
  149. package/dist/e2e/options.d.ts +123 -0
  150. package/dist/e2e/options.js +244 -0
  151. package/dist/e2e/page-scripts.d.ts +45 -0
  152. package/dist/e2e/page-scripts.js +53 -0
  153. package/dist/e2e/peers.d.ts +9 -0
  154. package/dist/e2e/peers.js +19 -0
  155. package/dist/e2e/plugins.d.ts +32 -0
  156. package/dist/e2e/plugins.js +119 -0
  157. package/dist/e2e/process-tree.d.ts +33 -0
  158. package/dist/e2e/process-tree.js +133 -0
  159. package/dist/e2e/readiness.d.ts +23 -0
  160. package/dist/e2e/readiness.js +63 -0
  161. package/dist/e2e/seed.d.ts +34 -0
  162. package/dist/e2e/seed.js +122 -0
  163. package/dist/e2e/session.d.ts +71 -0
  164. package/dist/e2e/session.js +266 -0
  165. package/dist/e2e/vault.d.ts +52 -0
  166. package/dist/e2e/vault.js +146 -0
  167. package/dist/e2e/version.d.ts +25 -0
  168. package/dist/e2e/version.js +40 -0
  169. package/dist/eslint/index.d.ts +2 -0
  170. package/dist/eslint/index.js +1 -0
  171. package/dist/eslint/obsidian-plugin.d.ts +49 -0
  172. package/dist/eslint/obsidian-plugin.js +115 -0
  173. package/dist/index.d.ts +3 -0
  174. package/dist/index.js +1 -0
  175. package/dist/kit/args.d.ts +7 -0
  176. package/dist/kit/args.js +21 -0
  177. package/dist/kit/commands.d.ts +3 -0
  178. package/dist/kit/commands.js +52 -0
  179. package/dist/kit/files.d.ts +3 -0
  180. package/dist/kit/files.js +24 -0
  181. package/dist/kit/pins.d.ts +89 -0
  182. package/dist/kit/pins.js +178 -0
  183. package/dist/kit/remote.d.ts +13 -0
  184. package/dist/kit/remote.js +33 -0
  185. package/dist/kit/runners.d.ts +11 -0
  186. package/dist/kit/runners.js +53 -0
  187. package/dist/kit/terminal-text.d.ts +6 -0
  188. package/dist/kit/terminal-text.js +20 -0
  189. package/dist/kit/upgrade.d.ts +26 -0
  190. package/dist/kit/upgrade.js +162 -0
  191. package/dist/peers/resolve.d.ts +8 -0
  192. package/dist/peers/resolve.js +28 -0
  193. package/dist/peers/versions.d.ts +30 -0
  194. package/dist/peers/versions.js +32 -0
  195. package/dist/release/api-check.d.ts +27 -0
  196. package/dist/release/api-check.js +119 -0
  197. package/dist/release/args.d.ts +40 -0
  198. package/dist/release/args.js +120 -0
  199. package/dist/release/assets.d.ts +21 -0
  200. package/dist/release/assets.js +35 -0
  201. package/dist/release/build-check.d.ts +43 -0
  202. package/dist/release/build-check.js +184 -0
  203. package/dist/release/build-script.d.ts +12 -0
  204. package/dist/release/build-script.js +30 -0
  205. package/dist/release/build-tagged.d.ts +26 -0
  206. package/dist/release/build-tagged.js +52 -0
  207. package/dist/release/bump.d.ts +24 -0
  208. package/dist/release/bump.js +58 -0
  209. package/dist/release/changelog.d.ts +25 -0
  210. package/dist/release/changelog.js +148 -0
  211. package/dist/release/check.d.ts +38 -0
  212. package/dist/release/check.js +150 -0
  213. package/dist/release/commands.d.ts +3 -0
  214. package/dist/release/commands.js +154 -0
  215. package/dist/release/committed-tree.d.ts +63 -0
  216. package/dist/release/committed-tree.js +118 -0
  217. package/dist/release/config.d.ts +3 -0
  218. package/dist/release/config.js +28 -0
  219. package/dist/release/gh-access.d.ts +14 -0
  220. package/dist/release/gh-access.js +45 -0
  221. package/dist/release/gh.d.ts +10 -0
  222. package/dist/release/gh.js +33 -0
  223. package/dist/release/git.d.ts +49 -0
  224. package/dist/release/git.js +111 -0
  225. package/dist/release/interrupt.d.ts +30 -0
  226. package/dist/release/interrupt.js +60 -0
  227. package/dist/release/json.d.ts +33 -0
  228. package/dist/release/json.js +81 -0
  229. package/dist/release/kit-check.d.ts +8 -0
  230. package/dist/release/kit-check.js +51 -0
  231. package/dist/release/manifest-rules.d.ts +23 -0
  232. package/dist/release/manifest-rules.js +255 -0
  233. package/dist/release/preflight.d.ts +10 -0
  234. package/dist/release/preflight.js +65 -0
  235. package/dist/release/problems.d.ts +24 -0
  236. package/dist/release/problems.js +11 -0
  237. package/dist/release/project-files.d.ts +14 -0
  238. package/dist/release/project-files.js +16 -0
  239. package/dist/release/publish-command.d.ts +21 -0
  240. package/dist/release/publish-command.js +83 -0
  241. package/dist/release/publish-git.d.ts +37 -0
  242. package/dist/release/publish-git.js +108 -0
  243. package/dist/release/publish-state.d.ts +29 -0
  244. package/dist/release/publish-state.js +70 -0
  245. package/dist/release/publish-verify.d.ts +41 -0
  246. package/dist/release/publish-verify.js +112 -0
  247. package/dist/release/publish-wait.d.ts +25 -0
  248. package/dist/release/publish-wait.js +56 -0
  249. package/dist/release/publish.d.ts +35 -0
  250. package/dist/release/publish.js +181 -0
  251. package/dist/release/release-assets.d.ts +39 -0
  252. package/dist/release/release-assets.js +68 -0
  253. package/dist/release/release.d.ts +37 -0
  254. package/dist/release/release.js +179 -0
  255. package/dist/release/remote.d.ts +12 -0
  256. package/dist/release/remote.js +15 -0
  257. package/dist/release/reproducible.d.ts +16 -0
  258. package/dist/release/reproducible.js +34 -0
  259. package/dist/release/run-tests.d.ts +5 -0
  260. package/dist/release/run-tests.js +17 -0
  261. package/dist/release/semver.d.ts +8 -0
  262. package/dist/release/semver.js +60 -0
  263. package/dist/release/version-rules.d.ts +28 -0
  264. package/dist/release/version-rules.js +63 -0
  265. package/dist/release/versions-json.d.ts +15 -0
  266. package/dist/release/versions-json.js +88 -0
  267. package/dist/release/workflow-run.d.ts +44 -0
  268. package/dist/release/workflow-run.js +71 -0
  269. package/dist/scanner/code-checks.d.ts +41 -0
  270. package/dist/scanner/code-checks.js +82 -0
  271. package/dist/scanner/commands.d.ts +3 -0
  272. package/dist/scanner/commands.js +43 -0
  273. package/dist/scanner/config.d.ts +7 -0
  274. package/dist/scanner/config.js +25 -0
  275. package/dist/scanner/css-check.d.ts +26 -0
  276. package/dist/scanner/css-check.js +63 -0
  277. package/dist/scanner/eslint-nesting.d.ts +16 -0
  278. package/dist/scanner/eslint-nesting.js +45 -0
  279. package/dist/scanner/findings.d.ts +23 -0
  280. package/dist/scanner/findings.js +21 -0
  281. package/dist/scanner/git-files.d.ts +16 -0
  282. package/dist/scanner/git-files.js +73 -0
  283. package/dist/scanner/lint.d.ts +47 -0
  284. package/dist/scanner/lint.js +163 -0
  285. package/dist/scanner/meta-checks.d.ts +8 -0
  286. package/dist/scanner/meta-checks.js +22 -0
  287. package/dist/scanner/outside-project.d.ts +19 -0
  288. package/dist/scanner/outside-project.js +20 -0
  289. package/dist/scanner/run.d.ts +19 -0
  290. package/dist/scanner/run.js +78 -0
  291. package/dist/scanner/scanner-config.d.ts +114 -0
  292. package/dist/scanner/scanner-config.js +207 -0
  293. package/dist/scanner/typescript-gate.d.ts +30 -0
  294. package/dist/scanner/typescript-gate.js +73 -0
  295. package/dist/vitest/build-config.d.ts +17 -0
  296. package/dist/vitest/build-config.js +106 -0
  297. package/dist/vitest/define-unit-config.d.ts +27 -0
  298. package/dist/vitest/define-unit-config.js +45 -0
  299. package/dist/vitest/dom/elements.d.ts +87 -0
  300. package/dist/vitest/dom/elements.js +291 -0
  301. package/dist/vitest/dom/index.d.ts +1 -0
  302. package/dist/vitest/dom/index.js +1 -0
  303. package/dist/vitest/dom/install.d.ts +8 -0
  304. package/dist/vitest/dom/install.js +261 -0
  305. package/dist/vitest/dom/setup.d.ts +1 -0
  306. package/dist/vitest/dom/setup.js +3 -0
  307. package/dist/vitest/index.d.ts +3 -0
  308. package/dist/vitest/index.js +2 -0
  309. package/dist/vitest/options.d.ts +92 -0
  310. package/dist/vitest/options.js +136 -0
  311. package/dist/vitest/peers.d.ts +10 -0
  312. package/dist/vitest/peers.js +51 -0
  313. package/dist/vitest/workspace-root.d.ts +7 -0
  314. package/dist/vitest/workspace-root.js +39 -0
  315. package/docs/build.md +232 -0
  316. package/docs/ci.md +182 -0
  317. package/docs/demo.md +364 -0
  318. package/docs/e2e.md +563 -0
  319. package/docs/release.md +374 -0
  320. package/docs/scanner.md +204 -0
  321. package/docs/unit.md +291 -0
  322. package/package.json +100 -4
  323. package/plugins/opdk/skills/audit/SKILL.md +81 -0
  324. package/plugins/opdk/skills/build/SKILL.md +79 -0
  325. package/plugins/opdk/skills/demo/SKILL.md +102 -0
  326. package/plugins/opdk/skills/e2e/SKILL.md +132 -0
  327. package/plugins/opdk/skills/release/SKILL.md +84 -0
  328. package/plugins/opdk/skills/scanner/SKILL.md +60 -0
  329. package/plugins/opdk/skills/unit/SKILL.md +90 -0
@@ -0,0 +1,65 @@
1
+ import { CONFIG_FILE_NAME, loadConfig } from "../config/load-config.js";
2
+ import { parseDemoArgs } from "./args.js";
3
+ const demoUsage = `Usage: opdk demo [names...]
4
+
5
+ Turns the films the demo fixture recorded into finished media, in the output folder
6
+ (default docs/screens): <name>.mp4, <name>.gif and <name>-poster.png for each film.
7
+
8
+ frames <demo.outDir>/films/<name>/ (default .opdk/demo), from manifest.json; only
9
+ films whose recording finished are encoded, the others are listed with why
10
+ mp4 x264, yuv420p, crf 20, preset slow, faststart, at the film's fps
11
+ gif its own palette, 128 colours, 10 fps (the film's fps when lower), as wide as
12
+ the frames up to 1000 px
13
+ poster the first frame, as wide as the MP4 (demo.poster: { width } or false)
14
+ stills <demo.outDir>/stills/<name>.png is copied to the output folder as <name>.png, only
15
+ when its bytes changed (demo.stills: false turns it off, { output } picks a folder).
16
+ A still recorded with out: "x" goes to the folder demo.outputs.x names; one with
17
+ publish: false is left where it is
18
+ layout "phone-captions" first puts each phone frame beside its caption list, in the
19
+ colours of the film's theme (needs electron and @playwright/test in the plugin,
20
+ like the e2e tests)
21
+
22
+ A file is written to a temporary name and moved into the output folder when it is
23
+ complete, so a failed encode keeps the previous file. The command never deletes media.
24
+
25
+ Checks, as "!" lines unless noted:
26
+ size a file above 2 MB warns, above 10 MB fails (the limit GitHub puts on images
27
+ and GIFs attached to issues and pull requests)
28
+ loop the film's last frame should equal its first, or the GIF jumps on repeat;
29
+ loop: "fail" makes it an error, "off" skips it
30
+ hold a frame held for less than one GIF frame can be skipped by the GIF
31
+ density frames shot below scale 2, or sizes that do not match the scale
32
+ pair a -light or -dark film whose partner film is missing
33
+ stale media in the output folder with no film or still behind it (never deleted)
34
+
35
+ Needs ffmpeg for films: on PATH, or its path in OPDK_FFMPEG. No audio, no intro or outro
36
+ cards. Without names every complete film is encoded and every still copied; a name selects
37
+ the film and the still of that name. Exit 1 when anything fails: no films and no stills, a
38
+ name that is neither a film nor a still, an incomplete film named on the command line,
39
+ without names no complete film among the recorded films, an unusable manifest,
40
+ a missing ffmpeg, an encode, a still that cannot be copied or would overwrite a film's file,
41
+ or a check set to fail.
42
+
43
+ Settings come from opdk.config.mjs ("demo" section): outDir, output, stills, outputs, films, and gif, mp4,
44
+ poster, layout, budget, loop, phone for all films or per film under films.<name>.
45
+ `;
46
+ export const demoCommand = {
47
+ name: "demo",
48
+ summary: "Turn recorded demo films into MP4, GIF and poster files",
49
+ usage: demoUsage,
50
+ async run(args, ctx) {
51
+ const { names } = parseDemoArgs(args);
52
+ const config = await loadConfig(ctx.cwd);
53
+ // Loaded here: the encoder code is not needed by any other command or by `opdk --help`.
54
+ const { runDemo } = await import("./run.js");
55
+ return runDemo({
56
+ cwd: ctx.cwd,
57
+ env: ctx.env,
58
+ names,
59
+ config: config.demo ?? {},
60
+ reporter: ctx.reporter,
61
+ source: `${CONFIG_FILE_NAME} "demo" section`,
62
+ });
63
+ },
64
+ };
65
+ export const demoCommands = [demoCommand];
@@ -0,0 +1,57 @@
1
+ import type { DemoConfig, DemoLayout, DemoLoopMode, DemoPhoneConfig } from "../config/types.js";
2
+ export declare const DEFAULT_OUTPUT_DIR = "docs/screens";
3
+ /** GitHub shows a README at about 1000 px; a wider GIF is scaled down by the browser and only costs bytes. */
4
+ export declare const MAX_AUTO_GIF_WIDTH = 1000;
5
+ export declare const DEFAULT_GIF_COLORS = 128;
6
+ export declare const DEFAULT_GIF_FPS = 10;
7
+ export declare const DEFAULT_WARN_BYTES: number;
8
+ /** GitHub's limit for an image or GIF attached to an issue or pull request. */
9
+ export declare const DEFAULT_FAIL_BYTES: number;
10
+ /** Checks and copies the `demo` section of `opdk.config.mjs`. Every error names the offending key. */
11
+ export declare function validateDemoConfig(value: unknown, source: string): DemoConfig;
12
+ /**
13
+ * A colour or font goes into a `<style>` rule of the page the phone layout renders. A value that could end the
14
+ * declaration, the rule or the element (`; { } < >`), start an escape (`\`), a comment (`/*`) or a request (`url(`)
15
+ * is a mistake (or worse), never something to quietly strip. Quotes are refused in a colour; a font list needs them
16
+ * around family names with spaces, so there they only have to come in pairs.
17
+ */
18
+ export declare function assertCssValue(value: string, what: string, kind?: "color" | "font"): string;
19
+ /** Everything a film needs to be encoded, after defaults and overrides are merged. */
20
+ export interface FilmSettings {
21
+ /** Null when the GIF is off. A null width means "from the frames". */
22
+ readonly gif: {
23
+ readonly width: number | null;
24
+ readonly colors: number;
25
+ readonly fps: number | null;
26
+ } | null;
27
+ readonly mp4: boolean;
28
+ /** Null when the poster is off. A null width means "the width of the frames". */
29
+ readonly poster: {
30
+ readonly width: number | null;
31
+ } | null;
32
+ readonly layout: DemoLayout;
33
+ readonly budget: {
34
+ readonly warnBytes: number;
35
+ readonly failBytes: number;
36
+ };
37
+ readonly loop: DemoLoopMode;
38
+ /** The `phone` entries that apply, weakest first: the top level of `demo`, then the base name, then the exact name. */
39
+ readonly phone: readonly DemoPhoneConfig[];
40
+ }
41
+ /** The name an override for a theme pair is filed under: `tour-dark` of a dark film reads the entry `tour`. */
42
+ export declare function baseFilmName(name: string, theme: "light" | "dark" | null): string;
43
+ /** Defaults, then the top level of `demo`, then `demo.films[<base name>]`, then `demo.films[<name>]`. */
44
+ export declare function resolveFilmSettings(config: DemoConfig, name: string, theme: "light" | "dark" | null, source: string): FilmSettings;
45
+ /** The two folders of the `demo` section with their defaults, still relative to the plugin root. */
46
+ export declare function demoFolders(config: DemoConfig): {
47
+ outDir: string;
48
+ output: string;
49
+ };
50
+ /**
51
+ * Whether stills are published and where to, still relative to the plugin root; null when `demo.stills` is `false`.
52
+ * `outputs` are the named folders of `demo.outputs`, for a still that asks for one.
53
+ */
54
+ export declare function stillsSettings(config: DemoConfig): {
55
+ output: string;
56
+ outputs: Readonly<Record<string, string>>;
57
+ } | null;
@@ -0,0 +1,337 @@
1
+ import { assertName } from "../e2e/demo/names.js";
2
+ import { DEFAULT_DEMO_OUT_DIR } from "../e2e/demo/options.js";
3
+ export const DEFAULT_OUTPUT_DIR = "docs/screens";
4
+ /** GitHub shows a README at about 1000 px; a wider GIF is scaled down by the browser and only costs bytes. */
5
+ export const MAX_AUTO_GIF_WIDTH = 1000;
6
+ export const DEFAULT_GIF_COLORS = 128;
7
+ export const DEFAULT_GIF_FPS = 10;
8
+ export const DEFAULT_WARN_BYTES = 2 * 1024 * 1024;
9
+ /** GitHub's limit for an image or GIF attached to an issue or pull request. */
10
+ export const DEFAULT_FAIL_BYTES = 10 * 1024 * 1024;
11
+ const LAYOUTS = ["plain", "phone-captions"];
12
+ const LOOP_MODES = ["warn", "fail", "off"];
13
+ const FILM_KEYS = ["gif", "mp4", "poster", "layout", "budget", "loop", "phone"];
14
+ const DEMO_KEYS = [...FILM_KEYS, "outDir", "output", "stills", "outputs", "films"];
15
+ const GIF_KEYS = ["width", "colors", "fps"];
16
+ const POSTER_KEYS = ["width"];
17
+ const STILLS_KEYS = ["output"];
18
+ const BUDGET_KEYS = ["warnBytes", "failBytes"];
19
+ const COLOR_KEYS = ["background", "text", "muted", "accent"];
20
+ const PHONE_KEYS = [...COLOR_KEYS, "font", "title", "light", "dark"];
21
+ /** Checks and copies the `demo` section of `opdk.config.mjs`. Every error names the offending key. */
22
+ export function validateDemoConfig(value, source) {
23
+ if (!isRecord(value)) {
24
+ throw new Error(`${source}: "demo" must be an object.`);
25
+ }
26
+ rejectUnknownKeys(value, DEMO_KEYS, "demo", source);
27
+ const outDir = optionalString(value, "outDir", "demo.outDir", source);
28
+ const output = optionalString(value, "output", "demo.output", source);
29
+ const stills = optionalStills(value, source);
30
+ const outputs = optionalOutputs(value, source);
31
+ const films = optionalFilms(value, source);
32
+ return {
33
+ ...validateFilmConfig(value, "demo", source),
34
+ ...(outDir !== undefined && { outDir }),
35
+ ...(output !== undefined && { output }),
36
+ ...(stills !== undefined && { stills }),
37
+ ...(outputs !== undefined && { outputs }),
38
+ ...(films !== undefined && { films }),
39
+ };
40
+ }
41
+ function validateFilmConfig(value, label, source) {
42
+ const gif = optionalGif(value, label, source);
43
+ const mp4 = optionalBoolean(value, "mp4", `${label}.mp4`, source);
44
+ const poster = optionalPoster(value, label, source);
45
+ const layout = optionalOneOf(value, "layout", `${label}.layout`, LAYOUTS, source);
46
+ const budget = optionalBudget(value, label, source);
47
+ const loop = optionalOneOf(value, "loop", `${label}.loop`, LOOP_MODES, source);
48
+ const phone = optionalPhone(value, label, source);
49
+ return {
50
+ ...(gif !== undefined && { gif }),
51
+ ...(mp4 !== undefined && { mp4 }),
52
+ ...(poster !== undefined && { poster }),
53
+ ...(layout !== undefined && { layout }),
54
+ ...(budget !== undefined && { budget }),
55
+ ...(loop !== undefined && { loop }),
56
+ ...(phone !== undefined && { phone }),
57
+ };
58
+ }
59
+ function optionalPoster(parent, label, source) {
60
+ const value = own(parent, "poster");
61
+ if (value === undefined || typeof value === "boolean") {
62
+ return value;
63
+ }
64
+ if (!isRecord(value)) {
65
+ throw new Error(`${source}: "${label}.poster" must be an object ({ width }) or true or false.`);
66
+ }
67
+ rejectUnknownKeys(value, POSTER_KEYS, `${label}.poster`, source);
68
+ const width = optionalInteger(value, "width", `${label}.poster.width`, 16, 8000, source);
69
+ return width === undefined ? {} : { width };
70
+ }
71
+ function optionalStills(parent, source) {
72
+ const value = own(parent, "stills");
73
+ if (value === undefined || typeof value === "boolean") {
74
+ return value;
75
+ }
76
+ if (!isRecord(value)) {
77
+ throw new Error(`${source}: "demo.stills" must be an object ({ output }) or true or false.`);
78
+ }
79
+ rejectUnknownKeys(value, STILLS_KEYS, "demo.stills", source);
80
+ const output = optionalString(value, "output", "demo.stills.output", source);
81
+ return output === undefined ? {} : { output };
82
+ }
83
+ function optionalOutputs(parent, source) {
84
+ const value = own(parent, "outputs");
85
+ if (value === undefined) {
86
+ return undefined;
87
+ }
88
+ if (!isRecord(value)) {
89
+ throw new Error(`${source}: "demo.outputs" must be an object from a folder name to a folder, for example { listing: "docs/listing" }.`);
90
+ }
91
+ const outputs = {};
92
+ for (const name of Object.keys(value)) {
93
+ try {
94
+ assertName(name, "demo.outputs key");
95
+ }
96
+ catch (error) {
97
+ throw new Error(`${source}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
98
+ }
99
+ const folder = optionalString(value, name, `demo.outputs[${JSON.stringify(name)}]`, source);
100
+ if (folder !== undefined) {
101
+ outputs[name] = folder;
102
+ }
103
+ }
104
+ return outputs;
105
+ }
106
+ function optionalGif(parent, label, source) {
107
+ const value = own(parent, "gif");
108
+ if (value === undefined || value === false) {
109
+ return value;
110
+ }
111
+ if (!isRecord(value)) {
112
+ throw new Error(`${source}: "${label}.gif" must be an object ({ width, colors, fps }) or false.`);
113
+ }
114
+ rejectUnknownKeys(value, GIF_KEYS, `${label}.gif`, source);
115
+ const width = optionalInteger(value, "width", `${label}.gif.width`, 16, 8000, source);
116
+ const colors = optionalInteger(value, "colors", `${label}.gif.colors`, 2, 256, source);
117
+ const fps = optionalInteger(value, "fps", `${label}.gif.fps`, 1, 50, source);
118
+ return {
119
+ ...(width !== undefined && { width }),
120
+ ...(colors !== undefined && { colors }),
121
+ ...(fps !== undefined && { fps }),
122
+ };
123
+ }
124
+ function optionalBudget(parent, label, source) {
125
+ const value = own(parent, "budget");
126
+ if (value === undefined) {
127
+ return undefined;
128
+ }
129
+ if (!isRecord(value)) {
130
+ throw new Error(`${source}: "${label}.budget" must be an object ({ warnBytes, failBytes }).`);
131
+ }
132
+ rejectUnknownKeys(value, BUDGET_KEYS, `${label}.budget`, source);
133
+ const warnBytes = optionalInteger(value, "warnBytes", `${label}.budget.warnBytes`, 1, Number.MAX_SAFE_INTEGER, source);
134
+ const failBytes = optionalInteger(value, "failBytes", `${label}.budget.failBytes`, 1, Number.MAX_SAFE_INTEGER, source);
135
+ if (warnBytes !== undefined && failBytes !== undefined && warnBytes > failBytes) {
136
+ throw new Error(`${source}: "${label}.budget.warnBytes" (${String(warnBytes)}) must not be above "failBytes" (${String(failBytes)}).`);
137
+ }
138
+ return { ...(warnBytes !== undefined && { warnBytes }), ...(failBytes !== undefined && { failBytes }) };
139
+ }
140
+ function optionalPhone(parent, label, source) {
141
+ const value = own(parent, "phone");
142
+ if (value === undefined) {
143
+ return undefined;
144
+ }
145
+ const where = `${label}.phone`;
146
+ if (!isRecord(value)) {
147
+ throw new Error(`${source}: "${where}" must be an object ({ background, text, muted, accent, font, title, light, dark }).`);
148
+ }
149
+ rejectUnknownKeys(value, PHONE_KEYS, where, source);
150
+ const light = optionalPhoneColors(value, "light", where, source);
151
+ const dark = optionalPhoneColors(value, "dark", where, source);
152
+ const font = optionalString(value, "font", `${where}.font`, source);
153
+ const title = optionalString(value, "title", `${where}.title`, source);
154
+ return {
155
+ ...readPhoneColors(value, where, source),
156
+ ...(light !== undefined && { light }),
157
+ ...(dark !== undefined && { dark }),
158
+ ...(font !== undefined && { font: assertCssValue(font, `${source}: "${where}.font"`, "font") }),
159
+ ...(title !== undefined && { title }),
160
+ };
161
+ }
162
+ function optionalPhoneColors(parent, key, where, source) {
163
+ const value = own(parent, key);
164
+ if (value === undefined) {
165
+ return undefined;
166
+ }
167
+ if (!isRecord(value)) {
168
+ throw new Error(`${source}: "${where}.${key}" must be an object ({ background, text, muted, accent }).`);
169
+ }
170
+ rejectUnknownKeys(value, COLOR_KEYS, `${where}.${key}`, source);
171
+ return readPhoneColors(value, `${where}.${key}`, source);
172
+ }
173
+ function readPhoneColors(record, where, source) {
174
+ const colors = {};
175
+ for (const key of COLOR_KEYS) {
176
+ const text = optionalString(record, key, `${where}.${key}`, source);
177
+ if (text !== undefined) {
178
+ colors[key] = assertCssValue(text, `${source}: "${where}.${key}"`, "color");
179
+ }
180
+ }
181
+ return colors;
182
+ }
183
+ function optionalFilms(parent, source) {
184
+ const value = own(parent, "films");
185
+ if (value === undefined) {
186
+ return undefined;
187
+ }
188
+ if (!isRecord(value)) {
189
+ throw new Error(`${source}: "demo.films" must be an object keyed by film name.`);
190
+ }
191
+ const films = {};
192
+ for (const [name, film] of Object.entries(value)) {
193
+ const label = `demo.films[${JSON.stringify(name)}]`;
194
+ if (!isRecord(film)) {
195
+ throw new Error(`${source}: "${label}" must be an object.`);
196
+ }
197
+ rejectUnknownKeys(film, FILM_KEYS, label, source);
198
+ films[name] = validateFilmConfig(film, label, source);
199
+ }
200
+ return films;
201
+ }
202
+ /**
203
+ * A colour or font goes into a `<style>` rule of the page the phone layout renders. A value that could end the
204
+ * declaration, the rule or the element (`; { } < >`), start an escape (`\`), a comment (`/*`) or a request (`url(`)
205
+ * is a mistake (or worse), never something to quietly strip. Quotes are refused in a colour; a font list needs them
206
+ * around family names with spaces, so there they only have to come in pairs.
207
+ */
208
+ export function assertCssValue(value, what, kind = "color") {
209
+ const forbidden = /[;{}<>\\]|\/\*|url\(/i.exec(value);
210
+ if (forbidden !== null) {
211
+ throw new Error(`${what} must be a CSS value without ${JSON.stringify(forbidden[0])}, got ${JSON.stringify(value)}.`);
212
+ }
213
+ const quotes = (char) => value.split(char).length - 1;
214
+ if (kind === "color" ? /["']/.test(value) : quotes('"') % 2 !== 0 || quotes("'") % 2 !== 0) {
215
+ throw new Error(`${what} must be a CSS value ${kind === "color" ? "without quotes" : "with quotes in pairs"}, got ${JSON.stringify(value)}.`);
216
+ }
217
+ return value;
218
+ }
219
+ /** The name an override for a theme pair is filed under: `tour-dark` of a dark film reads the entry `tour`. */
220
+ export function baseFilmName(name, theme) {
221
+ return theme !== null && name.endsWith(`-${theme}`) ? name.slice(0, -theme.length - 1) : name;
222
+ }
223
+ /** Defaults, then the top level of `demo`, then `demo.films[<base name>]`, then `demo.films[<name>]`. */
224
+ export function resolveFilmSettings(config, name, theme, source) {
225
+ const layers = [config];
226
+ const overrides = config.films ?? {};
227
+ const base = baseFilmName(name, theme);
228
+ for (const key of base === name ? [name] : [base, name]) {
229
+ const override = Object.hasOwn(overrides, key) ? overrides[key] : undefined;
230
+ if (override !== undefined) {
231
+ layers.push(override);
232
+ }
233
+ }
234
+ let gif = { width: null, colors: DEFAULT_GIF_COLORS, fps: null };
235
+ let mp4 = true;
236
+ let poster = { width: null };
237
+ let layout = "plain";
238
+ let loop = "warn";
239
+ const phone = [];
240
+ let warnBytes = DEFAULT_WARN_BYTES;
241
+ let failBytes = DEFAULT_FAIL_BYTES;
242
+ for (const layer of layers) {
243
+ if (layer.gif === false) {
244
+ gif = null;
245
+ }
246
+ else if (layer.gif !== undefined) {
247
+ gif = {
248
+ width: layer.gif.width ?? gif?.width ?? null,
249
+ colors: layer.gif.colors ?? gif?.colors ?? DEFAULT_GIF_COLORS,
250
+ fps: layer.gif.fps ?? gif?.fps ?? null,
251
+ };
252
+ }
253
+ mp4 = layer.mp4 ?? mp4;
254
+ if (layer.poster === false) {
255
+ poster = null;
256
+ }
257
+ else if (layer.poster !== undefined) {
258
+ poster = { width: (layer.poster === true ? undefined : layer.poster.width) ?? poster?.width ?? null };
259
+ }
260
+ layout = layer.layout ?? layout;
261
+ loop = layer.loop ?? loop;
262
+ if (layer.phone !== undefined) {
263
+ phone.push(layer.phone);
264
+ }
265
+ warnBytes = layer.budget?.warnBytes ?? warnBytes;
266
+ failBytes = layer.budget?.failBytes ?? failBytes;
267
+ }
268
+ if (warnBytes > failBytes) {
269
+ throw new Error(`${source}: the byte budget of film "${name}" has warnBytes (${String(warnBytes)}) above failBytes (${String(failBytes)}). ` +
270
+ `Set both in the same "budget" object.`);
271
+ }
272
+ return { gif, mp4, poster, layout, budget: { warnBytes, failBytes }, loop, phone };
273
+ }
274
+ /** The two folders of the `demo` section with their defaults, still relative to the plugin root. */
275
+ export function demoFolders(config) {
276
+ return { outDir: config.outDir ?? DEFAULT_DEMO_OUT_DIR, output: config.output ?? DEFAULT_OUTPUT_DIR };
277
+ }
278
+ /**
279
+ * Whether stills are published and where to, still relative to the plugin root; null when `demo.stills` is `false`.
280
+ * `outputs` are the named folders of `demo.outputs`, for a still that asks for one.
281
+ */
282
+ export function stillsSettings(config) {
283
+ const { stills } = config;
284
+ if (stills === false) {
285
+ return null;
286
+ }
287
+ const folder = typeof stills === "object" ? stills.output : undefined;
288
+ return { output: folder ?? config.output ?? DEFAULT_OUTPUT_DIR, outputs: config.outputs ?? {} };
289
+ }
290
+ function isRecord(value) {
291
+ if (typeof value !== "object" || value === null) {
292
+ return false;
293
+ }
294
+ const prototype = Object.getPrototypeOf(value);
295
+ return prototype === Object.prototype || prototype === null;
296
+ }
297
+ function own(record, key) {
298
+ return Object.hasOwn(record, key) ? record[key] : undefined;
299
+ }
300
+ function rejectUnknownKeys(record, allowed, label, source) {
301
+ const unknown = Object.keys(record).filter((key) => !allowed.includes(key));
302
+ if (unknown.length > 0) {
303
+ throw new Error(`${source}: unknown key(s) in "${label}": ${unknown.join(", ")}. Allowed keys: ${allowed.join(", ")}.`);
304
+ }
305
+ }
306
+ function optionalString(record, key, label, source) {
307
+ const value = own(record, key);
308
+ if (value !== undefined && (typeof value !== "string" || value === "")) {
309
+ throw new Error(`${source}: "${label}" must be a non-empty string.`);
310
+ }
311
+ return value;
312
+ }
313
+ function optionalBoolean(record, key, label, source) {
314
+ const value = own(record, key);
315
+ if (value !== undefined && typeof value !== "boolean") {
316
+ throw new Error(`${source}: "${label}" must be true or false.`);
317
+ }
318
+ return value;
319
+ }
320
+ function optionalInteger(record, key, label, min, max, source) {
321
+ const value = own(record, key);
322
+ if (value !== undefined && (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max)) {
323
+ throw new Error(`${source}: "${label}" must be a whole number from ${String(min)} to ${String(max)}.`);
324
+ }
325
+ return value;
326
+ }
327
+ function optionalOneOf(record, key, label, allowed, source) {
328
+ const value = own(record, key);
329
+ if (value === undefined) {
330
+ return undefined;
331
+ }
332
+ const found = allowed.find((item) => item === value);
333
+ if (found === undefined) {
334
+ throw new Error(`${source}: "${label}" must be one of: ${allowed.map((item) => JSON.stringify(item)).join(", ")}.`);
335
+ }
336
+ return found;
337
+ }
@@ -0,0 +1,18 @@
1
+ import { type FfmpegProbe } from "./ffmpeg.js";
2
+ /** What the demo run needs from ffmpeg; tests replace it. */
3
+ export interface FfmpegTool {
4
+ /** The command that runs, for messages. */
5
+ readonly command: string;
6
+ /** Runs ffmpeg; a non-zero exit, or any error it prints, throws with the tail of its stderr. */
7
+ run(args: readonly string[]): Promise<void>;
8
+ /** Runs ffmpeg and returns what it wrote to stdout. */
9
+ capture(args: readonly string[]): Promise<Buffer>;
10
+ /** The text of `ffmpeg -encoders`. */
11
+ encoders(): Promise<string>;
12
+ }
13
+ /** An encode of a long film at 2x takes a minute or two; ten minutes means ffmpeg is stuck (a pipe nobody reads, a dead disk). */
14
+ export declare const ENCODE_TIMEOUT_MS: number;
15
+ /** Whether `<command> -version` runs. */
16
+ export declare function probeFfmpeg(command: string): Promise<FfmpegProbe>;
17
+ /** `timeoutMs` bounds every encode; the default is `ENCODE_TIMEOUT_MS`. */
18
+ export declare function createFfmpegTool(command: string, timeoutMs?: number): FfmpegTool;
@@ -0,0 +1,59 @@
1
+ import { execFile } from "node:child_process";
2
+ import { stderrTail } from "./ffmpeg.js";
3
+ /** Large enough for a few 4K RGBA frames; ffmpeg's own diagnostics are small. */
4
+ const MAX_OUTPUT_BYTES = 512 * 1024 * 1024;
5
+ /** An encode of a long film at 2x takes a minute or two; ten minutes means ffmpeg is stuck (a pipe nobody reads, a dead disk). */
6
+ export const ENCODE_TIMEOUT_MS = 10 * 60 * 1000;
7
+ /** `-version` and `-encoders` answer at once. */
8
+ const PROBE_TIMEOUT_MS = 30 * 1000;
9
+ /**
10
+ * `strict` also fails a run that exited 0 but printed to stderr. The encodes run at `-v error`, so stderr holds
11
+ * errors only, and ffmpeg is known to exit 0 after it skipped a frame it could not decode (a truncated PNG),
12
+ * which would ship a film with a missing step.
13
+ */
14
+ function exec(command, args, timeoutMs, strict = false) {
15
+ return new Promise((resolve, reject) => {
16
+ const options = { encoding: "buffer", maxBuffer: MAX_OUTPUT_BYTES, timeout: timeoutMs, killSignal: "SIGKILL" };
17
+ execFile(command, [...args], options, (error, stdout, stderr) => {
18
+ if (error === null) {
19
+ const tail = stderrTail(stderr.toString("utf8"));
20
+ if (strict && tail !== "") {
21
+ reject(new Error(`${command} exited with code 0 but reported errors:\n${tail}`));
22
+ return;
23
+ }
24
+ resolve(stdout);
25
+ return;
26
+ }
27
+ const code = error.code;
28
+ const tail = stderrTail(stderr.toString("utf8"));
29
+ const timedOut = error.killed && error.signal === "SIGKILL";
30
+ const how = timedOut
31
+ ? `did not finish in ${String(timeoutMs / 1000)} s and was killed`
32
+ : typeof code === "number"
33
+ ? `exited with code ${String(code)}`
34
+ : `could not run (${error.message})`;
35
+ reject(new Error(`${command} ${how}${tail === "" ? "." : `:\n${tail}`}`, { cause: error }));
36
+ });
37
+ });
38
+ }
39
+ /** Whether `<command> -version` runs. */
40
+ export async function probeFfmpeg(command) {
41
+ try {
42
+ const stdout = await exec(command, ["-hide_banner", "-version"], PROBE_TIMEOUT_MS);
43
+ return { ok: true, version: stdout.toString("utf8").split("\n")[0]?.trim() ?? command };
44
+ }
45
+ catch (error) {
46
+ return { ok: false, error: error instanceof Error ? (error.message.split("\n")[0] ?? "") : String(error) };
47
+ }
48
+ }
49
+ /** `timeoutMs` bounds every encode; the default is `ENCODE_TIMEOUT_MS`. */
50
+ export function createFfmpegTool(command, timeoutMs = ENCODE_TIMEOUT_MS) {
51
+ return {
52
+ command,
53
+ run: async (args) => {
54
+ await exec(command, args, timeoutMs, true);
55
+ },
56
+ capture: (args) => exec(command, args, timeoutMs),
57
+ encoders: async () => (await exec(command, ["-hide_banner", "-encoders"], PROBE_TIMEOUT_MS)).toString("utf8"),
58
+ };
59
+ }
@@ -0,0 +1,63 @@
1
+ import type { FilmFrame } from "../e2e/demo/manifest.js";
2
+ /** Environment variable that points `opdk demo` at an ffmpeg binary (a build with libx264, say) instead of the one on PATH. */
3
+ export declare const FFMPEG_ENV = "OPDK_FFMPEG";
4
+ export declare const INSTALL_HINT: string;
5
+ /** What running `<command> -version` tells; `error` is set when the command could not run. */
6
+ export interface FfmpegProbe {
7
+ readonly ok: boolean;
8
+ /** First line of the version output. */
9
+ readonly version?: string;
10
+ readonly error?: string;
11
+ }
12
+ /** Picks the ffmpeg command: `OPDK_FFMPEG` when set (and then it must work), otherwise `ffmpeg` from PATH. */
13
+ export declare function locateFfmpeg(env: Readonly<Record<string, string | undefined>>, probe: (command: string) => Promise<FfmpegProbe>): Promise<{
14
+ command: string;
15
+ version: string;
16
+ }>;
17
+ /** Seconds the film runs: the sum of the frame holds. */
18
+ export declare function totalHold(frames: readonly FilmFrame[]): number;
19
+ /**
20
+ * The concat demuxer list for a film: each frame with its own `duration`.
21
+ *
22
+ * The demuxer ignores the duration of the last entry unless that file is listed once more after it, so the last
23
+ * frame is repeated. The repeat plays the whole last hold a second time (holds of 1 s and 2 s run 5 s; without the
24
+ * repeat the last hold is not honoured), which is why the encodes also pass `-t <total hold>`: it cuts the film
25
+ * back to the sum of the holds.
26
+ *
27
+ * Every entry also sets `option pattern_type none`. The concat demuxer opens each entry with the image2 demuxer, which
28
+ * reads a `%d` in the path as a numbered sequence ("opdk-100%d-x/frame.png" is then looked for as frame 0 to 4 and
29
+ * not found). The error names the list file, not the entry. `-pattern_type none` on the command line does not reach
30
+ * the entries; the `option` line does, and the same list works on macOS and Linux ffmpeg.
31
+ */
32
+ export declare function buildConcatList(dir: string, frames: readonly FilmFrame[]): string;
33
+ /** MP4 for the web: x264, yuv420p (the only format every browser and phone plays), even dimensions, moov atom first. */
34
+ export declare function mp4Args(params: {
35
+ list: string;
36
+ frames: readonly FilmFrame[];
37
+ fps: number;
38
+ out: string;
39
+ }): string[];
40
+ /** GIF with its own palette: `stats_mode=diff` spends colours on what moves, bayer dithering stays small on flat UI. */
41
+ export declare function gifArgs(params: {
42
+ list: string;
43
+ frames: readonly FilmFrame[];
44
+ fps: number;
45
+ width: number;
46
+ colors: number;
47
+ out: string;
48
+ }): string[];
49
+ /** The poster: the first frame at `width`. `-update 1` writes the output as one picture even when its path has a `%d`. */
50
+ export declare function posterArgs(params: {
51
+ frame: string;
52
+ width: number;
53
+ out: string;
54
+ }): string[];
55
+ /** Decodes one picture to raw RGBA on stdout, for comparing pixels. */
56
+ export declare function rawFrameArgs(frame: string): string[];
57
+ /** The last non-empty lines of ffmpeg's stderr, where it says what went wrong. */
58
+ export declare function stderrTail(stderr: string, lines?: number): string;
59
+ /** GIF width: the configured one, else the frame width capped at `maxAuto`; never above the frame width. */
60
+ export declare function resolveGifWidth(configured: number | null, frameWidth: number, maxAuto: number): {
61
+ width: number;
62
+ clamped: boolean;
63
+ };