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 @@
1
+ export {};
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Reads the kit's own version. The path is resolved from the module file, not from cwd,
3
+ * so it works the same from src/cli (tests) and dist/cli (installed).
4
+ */
5
+ export declare function readKitVersion(fromUrl: string): string;
6
+ /**
7
+ * Reads the short git commit `scripts/write-build-info.mjs` wrote to `dist/build-info.json` at build time.
8
+ * Returns undefined when the file is missing (running from `src/`, or a build without a git checkout) or holds
9
+ * no commit; a file that is not valid JSON is an error, because only the build writes it.
10
+ */
11
+ export declare function readKitCommit(fromUrl: string): string | undefined;
12
+ /** `0.0.0 (3613c4f)` when the commit is known, else just the version. */
13
+ export declare function describeKitVersion(fromUrl: string): string;
@@ -0,0 +1,61 @@
1
+ import { readFileSync } from "node:fs";
2
+ /**
3
+ * Reads the kit's own version. The path is resolved from the module file, not from cwd,
4
+ * so it works the same from src/cli (tests) and dist/cli (installed).
5
+ */
6
+ export function readKitVersion(fromUrl) {
7
+ const packageUrl = new URL("../../package.json", fromUrl);
8
+ let parsed;
9
+ try {
10
+ parsed = JSON.parse(readFileSync(packageUrl, "utf8"));
11
+ }
12
+ catch (error) {
13
+ throw new Error(`Cannot read the kit's package.json at ${packageUrl.href}: ${errorMessage(error)}`, {
14
+ cause: error,
15
+ });
16
+ }
17
+ if (typeof parsed === "object" && parsed !== null && "version" in parsed && typeof parsed.version === "string") {
18
+ return parsed.version;
19
+ }
20
+ throw new Error(`The kit's package.json at ${packageUrl.href} has no string "version".`);
21
+ }
22
+ /**
23
+ * Reads the short git commit `scripts/write-build-info.mjs` wrote to `dist/build-info.json` at build time.
24
+ * Returns undefined when the file is missing (running from `src/`, or a build without a git checkout) or holds
25
+ * no commit; a file that is not valid JSON is an error, because only the build writes it.
26
+ */
27
+ export function readKitCommit(fromUrl) {
28
+ const infoUrl = new URL("../build-info.json", fromUrl);
29
+ let text;
30
+ try {
31
+ text = readFileSync(infoUrl, "utf8");
32
+ }
33
+ catch (error) {
34
+ if (error instanceof Error && "code" in error && error.code === "ENOENT") {
35
+ return undefined;
36
+ }
37
+ throw new Error(`Cannot read the kit's build info at ${infoUrl.href}: ${errorMessage(error)}`, { cause: error });
38
+ }
39
+ let parsed;
40
+ try {
41
+ parsed = JSON.parse(text);
42
+ }
43
+ catch (error) {
44
+ throw new Error(`The kit's build info at ${infoUrl.href} is not valid JSON: ${errorMessage(error)}. Rebuild the kit with \`npm run build\`.`, {
45
+ cause: error,
46
+ });
47
+ }
48
+ if (typeof parsed === "object" && parsed !== null && "commit" in parsed && typeof parsed.commit === "string" && parsed.commit !== "") {
49
+ return parsed.commit;
50
+ }
51
+ return undefined;
52
+ }
53
+ /** `0.0.0 (3613c4f)` when the commit is known, else just the version. */
54
+ export function describeKitVersion(fromUrl) {
55
+ const version = readKitVersion(fromUrl);
56
+ const commit = readKitCommit(fromUrl);
57
+ return commit === undefined ? version : `${version} (${commit})`;
58
+ }
59
+ function errorMessage(error) {
60
+ return error instanceof Error ? error.message : String(error);
61
+ }
@@ -0,0 +1,3 @@
1
+ import type { OpdkConfig } from "./types.js";
2
+ /** Identity helper that gives `opdk.config.mjs` type checking and editor completion. */
3
+ export declare function defineConfig(config: OpdkConfig): OpdkConfig;
@@ -0,0 +1,4 @@
1
+ /** Identity helper that gives `opdk.config.mjs` type checking and editor completion. */
2
+ export function defineConfig(config) {
3
+ return config;
4
+ }
@@ -0,0 +1,6 @@
1
+ import { type OpdkConfig } from "./types.js";
2
+ export declare const CONFIG_FILE_NAME = "opdk.config.mjs";
3
+ /** Loads `<cwd>/opdk.config.mjs`. A missing file is not an error: it means "all defaults". */
4
+ export declare function loadConfig(cwd: string): Promise<OpdkConfig>;
5
+ /** Checks the shape of a config value. Exported for tests and for modules that build configs in code. */
6
+ export declare function validateConfig(value: unknown, source: string): OpdkConfig;
@@ -0,0 +1,70 @@
1
+ import { statSync } from "node:fs";
2
+ import path from "node:path";
3
+ import { pathToFileURL } from "node:url";
4
+ import { validateBuildConfig } from "../build/config.js";
5
+ import { validateDemoConfig } from "../demo/config.js";
6
+ import { validateReleaseConfig } from "../release/config.js";
7
+ import { validateScanConfig } from "../scanner/config.js";
8
+ import { CONFIG_SECTIONS } from "./types.js";
9
+ export const CONFIG_FILE_NAME = "opdk.config.mjs";
10
+ /** Loads `<cwd>/opdk.config.mjs`. A missing file is not an error: it means "all defaults". */
11
+ export async function loadConfig(cwd) {
12
+ const file = path.join(cwd, CONFIG_FILE_NAME);
13
+ if (!isFile(file)) {
14
+ return {};
15
+ }
16
+ let loaded;
17
+ try {
18
+ loaded = await import(pathToFileURL(file).href);
19
+ }
20
+ catch (error) {
21
+ throw new Error(`Cannot load ${file}: ${error instanceof Error ? error.message : String(error)}`, {
22
+ cause: error,
23
+ });
24
+ }
25
+ const exported = typeof loaded === "object" && loaded !== null && "default" in loaded ? loaded.default : undefined;
26
+ return validateConfig(exported, file);
27
+ }
28
+ /** Checks the shape of a config value. Exported for tests and for modules that build configs in code. */
29
+ export function validateConfig(value, source) {
30
+ if (value === undefined) {
31
+ throw new Error(`${source} has no default export. Use: export default defineConfig({ ... });`);
32
+ }
33
+ if (!isPlainObject(value)) {
34
+ throw new Error(`${source} must export a plain object as its default export.`);
35
+ }
36
+ const allowed = Object.keys(CONFIG_SECTIONS);
37
+ const unknownKeys = Object.keys(value).filter((key) => !allowed.includes(key));
38
+ if (unknownKeys.length > 0) {
39
+ throw new Error(`${source} has unknown top-level key(s): ${unknownKeys.join(", ")}. Allowed keys: ${allowed.join(", ")}.`);
40
+ }
41
+ // Modules validate and copy their own section here when they add one.
42
+ const build = Object.hasOwn(value, "build") ? value.build : undefined;
43
+ const scan = Object.hasOwn(value, "scan") ? value.scan : undefined;
44
+ const demo = Object.hasOwn(value, "demo") ? value.demo : undefined;
45
+ const release = Object.hasOwn(value, "release") ? value.release : undefined;
46
+ return {
47
+ ...(build !== undefined && { build: validateBuildConfig(build, source) }),
48
+ ...(scan !== undefined && { scan: validateScanConfig(scan, source) }),
49
+ ...(demo !== undefined && { demo: validateDemoConfig(demo, source) }),
50
+ ...(release !== undefined && { release: validateReleaseConfig(release, source) }),
51
+ };
52
+ }
53
+ function isPlainObject(value) {
54
+ if (typeof value !== "object" || value === null) {
55
+ return false;
56
+ }
57
+ const prototype = Object.getPrototypeOf(value);
58
+ return prototype === Object.prototype || prototype === null;
59
+ }
60
+ function isFile(file) {
61
+ try {
62
+ return statSync(file).isFile();
63
+ }
64
+ catch (error) {
65
+ if (error instanceof Error && "code" in error && error.code === "ENOENT") {
66
+ return false;
67
+ }
68
+ throw error;
69
+ }
70
+ }
@@ -0,0 +1,3 @@
1
+ import type { Manifest } from "./types.js";
2
+ /** Reads and validates `<cwd>/manifest.json`, the single source of the plugin id and name. */
3
+ export declare function readManifest(cwd: string): Manifest;
@@ -0,0 +1,72 @@
1
+ import { readFileSync } from "node:fs";
2
+ import path from "node:path";
3
+ /** Reads and validates `<cwd>/manifest.json`, the single source of the plugin id and name. */
4
+ export function readManifest(cwd) {
5
+ const file = path.join(cwd, "manifest.json");
6
+ let text;
7
+ try {
8
+ text = readFileSync(file, "utf8");
9
+ }
10
+ catch (error) {
11
+ if (error instanceof Error && "code" in error && error.code === "ENOENT") {
12
+ throw new Error(`No manifest.json in ${cwd}. Run opdk from the plugin root.`, { cause: error });
13
+ }
14
+ throw new Error(`Cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`, {
15
+ cause: error,
16
+ });
17
+ }
18
+ let parsed;
19
+ try {
20
+ parsed = JSON.parse(text);
21
+ }
22
+ catch (error) {
23
+ throw new Error(`${file} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, {
24
+ cause: error,
25
+ });
26
+ }
27
+ return validateManifest(parsed, file);
28
+ }
29
+ function validateManifest(value, file) {
30
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
31
+ throw new Error(`${file} must contain a JSON object.`);
32
+ }
33
+ const record = value;
34
+ const id = requireString(record, "id", file);
35
+ const name = requireString(record, "name", file);
36
+ const version = requireString(record, "version", file);
37
+ const description = optionalString(record, "description", file);
38
+ const minAppVersion = optionalString(record, "minAppVersion", file);
39
+ const isDesktopOnly = optionalBoolean(record, "isDesktopOnly", file);
40
+ return {
41
+ id,
42
+ name,
43
+ version,
44
+ ...(description !== undefined && { description }),
45
+ ...(minAppVersion !== undefined && { minAppVersion }),
46
+ ...(isDesktopOnly !== undefined && { isDesktopOnly }),
47
+ };
48
+ }
49
+ function requireString(record, key, file) {
50
+ const value = ownValue(record, key);
51
+ if (typeof value !== "string" || value === "") {
52
+ throw new Error(`${file}: "${key}" is required and must be a non-empty string.`);
53
+ }
54
+ return value;
55
+ }
56
+ function optionalString(record, key, file) {
57
+ const value = ownValue(record, key);
58
+ if (value !== undefined && typeof value !== "string") {
59
+ throw new Error(`${file}: "${key}" must be a string when present.`);
60
+ }
61
+ return value;
62
+ }
63
+ function optionalBoolean(record, key, file) {
64
+ const value = ownValue(record, key);
65
+ if (value !== undefined && typeof value !== "boolean") {
66
+ throw new Error(`${file}: "${key}" must be a boolean when present.`);
67
+ }
68
+ return value;
69
+ }
70
+ function ownValue(record, key) {
71
+ return Object.hasOwn(record, key) ? record[key] : undefined;
72
+ }
@@ -0,0 +1,146 @@
1
+ /** esbuild loaders accepted in `build.loader`. */
2
+ export declare const BUILD_LOADERS: readonly ["base64", "binary", "copy", "css", "dataurl", "default", "empty", "file", "js", "json", "jsx", "local-css", "text", "ts", "tsx"];
3
+ export type BuildLoader = (typeof BUILD_LOADERS)[number];
4
+ /** `build.css`: the stylesheet bundler's entry and output, relative to the plugin root. */
5
+ export interface BuildCssConfig {
6
+ /** Default `src/styles/main.css`. */
7
+ readonly entry?: string;
8
+ /** Default `styles.css`. */
9
+ readonly outfile?: string;
10
+ }
11
+ /** `build` section. Every key is optional; defaults are one plugin's release build. */
12
+ export interface BuildConfig {
13
+ /** Default `src/main.ts`. */
14
+ readonly entry?: string;
15
+ /** Default `main.js`. */
16
+ readonly outfile?: string;
17
+ /** Default `true`. */
18
+ readonly minify?: boolean;
19
+ /** esbuild target. Default `es2020`. */
20
+ readonly target?: string;
21
+ /** Added to the always-external `obsidian`, `electron`, `@codemirror/state`, `@codemirror/view`. */
22
+ readonly external?: readonly string[];
23
+ /** esbuild loader map, for example `{ ".png": "dataurl" }`. */
24
+ readonly loader?: Readonly<Record<string, BuildLoader>>;
25
+ /** CSS bundler settings, or `false` to skip the CSS step. */
26
+ readonly css?: BuildCssConfig | false;
27
+ }
28
+ /** `scan` section. It has no keys: every file the scanner reads counts (`scan.ignore` was removed). */
29
+ export type ScanConfig = Readonly<Record<string, never>>;
30
+ /** `release` section. Every key is optional. */
31
+ export interface ReleaseConfig {
32
+ /** Changelog file relative to the plugin root. Default `CHANGELOG.md`. */
33
+ readonly changelog?: string;
34
+ /** Branch releases are cut from. Default: the branch `origin/HEAD` points at. */
35
+ readonly defaultBranch?: string;
36
+ }
37
+ export type DemoLayout = "plain" | "phone-captions";
38
+ /** `demo.gif` and the per-film `gif`: how the GIF is made. */
39
+ export interface DemoGifConfig {
40
+ /** Pixels. Default: the frame width, at most 1000 (GitHub shows a README at about that width). Never wider than the frames. */
41
+ readonly width?: number;
42
+ /** Palette size, 2 to 256. Default 128. */
43
+ readonly colors?: number;
44
+ /** Frames per second, 1 to 50. Default: 10, or the film's fps when that is lower. A value set here is used as given. */
45
+ readonly fps?: number;
46
+ }
47
+ /** `demo.poster` and the per-film `poster`: the still of the first frame. */
48
+ export interface DemoPosterConfig {
49
+ /** Pixels. Default: the width of the MP4, so the poster is as sharp as the video it stands in for. Never wider than the frames. */
50
+ readonly width?: number;
51
+ }
52
+ /** `demo.budget` and the per-film `budget`: sizes of one finished file, in bytes. */
53
+ export interface DemoBudgetConfig {
54
+ /** A file above this prints a warning. Default 2 MB (2097152). */
55
+ readonly warnBytes?: number;
56
+ /** A file above this fails the command. Default 10 MB (10485760), GitHub's limit for images and GIFs attached to issues and pull requests. */
57
+ readonly failBytes?: number;
58
+ }
59
+ /** What `opdk demo` does when the last frame of a film is not the first one (the GIF would jump when it loops). */
60
+ export type DemoLoopMode = "warn" | "fail" | "off";
61
+ /** The four colours of the `"phone-captions"` layout. Values go into CSS: none may contain `;{}<>\`, `/*` or `url(`, and quotes are refused. */
62
+ export interface DemoPhoneColors {
63
+ readonly background?: string;
64
+ readonly text?: string;
65
+ /** Colour of the captions that are not the current step. */
66
+ readonly muted?: string;
67
+ /** Colour of the current step's number. */
68
+ readonly accent?: string;
69
+ }
70
+ /**
71
+ * `demo.phone` and the per-film `phone`: colours, font and title of the `"phone-captions"` layout.
72
+ *
73
+ * The colours can be set for both themes at the top level, and per theme under `light` and `dark`; a film shot in a
74
+ * theme (`demo.themes()`) reads its own entry on top of the top level. A film without a theme reads the top level
75
+ * and the light defaults.
76
+ */
77
+ export interface DemoPhoneConfig extends DemoPhoneColors {
78
+ readonly light?: DemoPhoneColors;
79
+ readonly dark?: DemoPhoneColors;
80
+ /** CSS font-family list, checked like the colours except that balanced quotes are allowed. Default: the stack Obsidian uses for its interface. */
81
+ readonly font?: string;
82
+ /** Heading above the caption list; none by default. HTML-escaped; a `\n` starts a new line. */
83
+ readonly title?: string;
84
+ }
85
+ /** What can be set for every film (top level of `demo`) or for one film (`demo.films.<name>`). */
86
+ export interface DemoFilmConfig {
87
+ /** An object tunes the GIF, `false` skips it. Default on. */
88
+ readonly gif?: DemoGifConfig | false;
89
+ /** Default `true`. */
90
+ readonly mp4?: boolean;
91
+ /** `false` skips the poster, `true` or an object makes it. Default on. */
92
+ readonly poster?: DemoPosterConfig | boolean;
93
+ /** `"plain"` encodes the frames as shot; `"phone-captions"` first puts each phone frame beside its caption list. Default `"plain"`. */
94
+ readonly layout?: DemoLayout;
95
+ readonly budget?: DemoBudgetConfig;
96
+ /** Default `"warn"`. The check compares the film's own first and last frame, before any layout. */
97
+ readonly loop?: DemoLoopMode;
98
+ readonly phone?: DemoPhoneConfig;
99
+ }
100
+ /** `demo.stills`: where the stills of `demo.still()` are published. */
101
+ export interface DemoStillsConfig {
102
+ /** Folder for the stills, relative to the plugin root. Default: `demo.output`, next to the films. */
103
+ readonly output?: string;
104
+ }
105
+ /** `demo` section. Every key is optional. */
106
+ export interface DemoConfig extends DemoFilmConfig {
107
+ /** Where the `demo` fixture wrote films and stills; the same default as the fixture, `.opdk/demo`. */
108
+ readonly outDir?: string;
109
+ /** Where the finished media go, relative to the plugin root. Default `docs/screens`. `opdk demo` adds files and replaces files of the same name; it never deletes. */
110
+ readonly output?: string;
111
+ /** `false` leaves the stills in `outDir`, an object publishes them to its own folder. Default on: every `<outDir>/stills/<name>.png` is copied to `output` as `<name>.png`, when its bytes changed. */
112
+ readonly stills?: DemoStillsConfig | boolean;
113
+ /**
114
+ * Named output folders for stills, relative to the plugin root: `{ listing: "docs/listing" }`. A still recorded
115
+ * with `demo.still(name, { out: "listing" })` is copied there instead of the default folder. A still that names a
116
+ * folder missing here fails the run. Not used with `stills: false`.
117
+ */
118
+ readonly outputs?: Readonly<Record<string, string>>;
119
+ /** Overrides by film name. A theme pair (`x-light`, `x-dark`) also reads the entry `x`; the exact name wins. */
120
+ readonly films?: Readonly<Record<string, DemoFilmConfig>>;
121
+ }
122
+ /**
123
+ * Per-plugin settings from `opdk.config.mjs`. Each kit module adds one optional section
124
+ * here (for example `build?: BuildConfig`) and registers its key in CONFIG_SECTIONS.
125
+ * Plugin id and name never live here: they come from manifest.json.
126
+ */
127
+ export interface OpdkConfig {
128
+ readonly build?: BuildConfig;
129
+ readonly scan?: ScanConfig;
130
+ readonly demo?: DemoConfig;
131
+ readonly release?: ReleaseConfig;
132
+ }
133
+ /**
134
+ * One entry per OpdkConfig key. The Record type makes the compiler demand an entry
135
+ * when a section is added, so the allowed-keys check cannot drift from the type.
136
+ */
137
+ export declare const CONFIG_SECTIONS: Record<keyof OpdkConfig, true>;
138
+ /** The subset of manifest.json the kit reads. */
139
+ export interface Manifest {
140
+ readonly id: string;
141
+ readonly name: string;
142
+ readonly version: string;
143
+ readonly description?: string;
144
+ readonly minAppVersion?: string;
145
+ readonly isDesktopOnly?: boolean;
146
+ }
@@ -0,0 +1,23 @@
1
+ /** esbuild loaders accepted in `build.loader`. */
2
+ export const BUILD_LOADERS = [
3
+ "base64",
4
+ "binary",
5
+ "copy",
6
+ "css",
7
+ "dataurl",
8
+ "default",
9
+ "empty",
10
+ "file",
11
+ "js",
12
+ "json",
13
+ "jsx",
14
+ "local-css",
15
+ "text",
16
+ "ts",
17
+ "tsx",
18
+ ];
19
+ /**
20
+ * One entry per OpdkConfig key. The Record type makes the compiler demand an entry
21
+ * when a section is added, so the allowed-keys check cannot drift from the type.
22
+ */
23
+ export const CONFIG_SECTIONS = { build: true, scan: true, demo: true, release: true };
@@ -0,0 +1,4 @@
1
+ /** Film names given on the command line; every other argument is an error, so a typo in a flag never passes for a name. */
2
+ export declare function parseDemoArgs(args: readonly string[]): {
3
+ names: string[];
4
+ };
@@ -0,0 +1,13 @@
1
+ /** Film names given on the command line; every other argument is an error, so a typo in a flag never passes for a name. */
2
+ export function parseDemoArgs(args) {
3
+ const names = [];
4
+ for (const arg of args) {
5
+ if (arg.startsWith("-")) {
6
+ throw new Error(`"opdk demo" has no option "${arg}". It takes film names; see "opdk demo --help".`);
7
+ }
8
+ if (!names.includes(arg)) {
9
+ names.push(arg);
10
+ }
11
+ }
12
+ return { names };
13
+ }
@@ -0,0 +1,56 @@
1
+ import type { FilmFrame, FilmManifest } from "../e2e/demo/manifest.js";
2
+ /** `340 KB`, or `1.4 MB` from a megabyte up (1 KB = 1024 bytes, like the budgets). */
3
+ export declare function formatBytes(bytes: number): string;
4
+ export type BudgetVerdict = "ok" | "warn" | "fail";
5
+ /** A file is over budget when it is larger than the limit; exactly the limit is fine. */
6
+ export declare function budgetVerdict(bytes: number, budget: {
7
+ warnBytes: number;
8
+ failBytes: number;
9
+ }): BudgetVerdict;
10
+ export interface StaleOutputs {
11
+ /** Recorded files whose film has no manifest any more (renamed or deleted test). */
12
+ readonly goneFilms: string[];
13
+ /** Recorded files of a film that still exists and encoded cleanly this run without writing them (an output turned off, or moved). */
14
+ readonly notWritten: string[];
15
+ }
16
+ /**
17
+ * Media the kit published earlier (`published`: output path to film name, from the record) that is still on disk and
18
+ * that no film produces any more: its film has no manifest (`currentFilms` lists the films that do), or its film
19
+ * encoded without failures in this run (`encoded`) and did not write it (`written`: output path to film name). A film
20
+ * that failed or was not selected proves nothing about its files. Sorted; nothing is deleted. Files the kit never wrote
21
+ * are not in the record, so pictures that merely share the folder are never named.
22
+ */
23
+ export declare function findStaleOutputs(published: Readonly<Record<string, string>>, currentFilms: ReadonlySet<string>, exists: (file: string) => boolean, current: {
24
+ readonly encoded: ReadonlySet<string>;
25
+ readonly written: Readonly<Record<string, string>>;
26
+ }): StaleOutputs;
27
+ /** Problems with the pixel density a film was shot at, from its manifest alone. */
28
+ export declare function densityWarnings(manifest: FilmManifest): string[];
29
+ /**
30
+ * Frames that are shown for less than one GIF frame (`1 / gifFps` seconds). The GIF samples the film at its fps, so
31
+ * such a frame can be skipped and the step is missing from the GIF. Null when every frame is held long enough.
32
+ */
33
+ export declare function shortHoldWarning(frames: readonly FilmFrame[], gifFps: number): string | null;
34
+ /** Where two RGBA pictures of the same size differ. */
35
+ export interface FrameDifference {
36
+ /** Top-left corner of the box around every differing pixel, in frame pixels. */
37
+ readonly x: number;
38
+ readonly y: number;
39
+ readonly width: number;
40
+ readonly height: number;
41
+ /** Share of differing pixels, 0 to 1. */
42
+ readonly ratio: number;
43
+ }
44
+ /**
45
+ * Largest difference per colour channel (of 255) that still counts as the same pixel. Video-grade antialiasing and
46
+ * compositing noise (a caret fade, a subpixel shift of text) stays within a few shades; one plugin's loop differed by 0.9%
47
+ * of the pixels at one shade and looked identical. 8 is invisible to the eye and far below a real change (a changed
48
+ * label, a toggled control, a moved highlight differ by dozens of shades).
49
+ */
50
+ export declare const CHANNEL_TOLERANCE = 8;
51
+ /**
52
+ * Compares two raw RGBA buffers of `width` x `height`; null when every pixel matches within `tolerance` per channel
53
+ * (alpha included). Differences above it are reported as a box and a share, as before.
54
+ */
55
+ export declare function compareFrames(a: Buffer, b: Buffer, width: number, height: number, tolerance?: number): FrameDifference | null;
56
+ export declare function describeLoopDifference(difference: FrameDifference): string;
@@ -0,0 +1,124 @@
1
+ /** `340 KB`, or `1.4 MB` from a megabyte up (1 KB = 1024 bytes, like the budgets). */
2
+ export function formatBytes(bytes) {
3
+ if (bytes >= 1024 * 1024) {
4
+ return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
5
+ }
6
+ return `${String(Math.max(1, Math.round(bytes / 1024)))} KB`;
7
+ }
8
+ /** A file is over budget when it is larger than the limit; exactly the limit is fine. */
9
+ export function budgetVerdict(bytes, budget) {
10
+ if (bytes > budget.failBytes) {
11
+ return "fail";
12
+ }
13
+ return bytes > budget.warnBytes ? "warn" : "ok";
14
+ }
15
+ /**
16
+ * Media the kit published earlier (`published`: output path to film name, from the record) that is still on disk and
17
+ * that no film produces any more: its film has no manifest (`currentFilms` lists the films that do), or its film
18
+ * encoded without failures in this run (`encoded`) and did not write it (`written`: output path to film name). A film
19
+ * that failed or was not selected proves nothing about its files. Sorted; nothing is deleted. Files the kit never wrote
20
+ * are not in the record, so pictures that merely share the folder are never named.
21
+ */
22
+ export function findStaleOutputs(published, currentFilms, exists, current) {
23
+ const goneFilms = [];
24
+ const notWritten = [];
25
+ for (const [file, film] of Object.entries(published)) {
26
+ if (!exists(file)) {
27
+ continue;
28
+ }
29
+ if (!currentFilms.has(film)) {
30
+ goneFilms.push(file);
31
+ }
32
+ else if (current.encoded.has(film) && !Object.hasOwn(current.written, file)) {
33
+ notWritten.push(file);
34
+ }
35
+ }
36
+ return { goneFilms: goneFilms.sort(), notWritten: notWritten.sort() };
37
+ }
38
+ /** Problems with the pixel density a film was shot at, from its manifest alone. */
39
+ export function densityWarnings(manifest) {
40
+ const warnings = [];
41
+ if (manifest.scale < 2) {
42
+ warnings.push(`shot at scale ${String(manifest.scale)}: on a Retina screen the film is shown at twice its size and looks soft. Shoot at scale 2 (the demo fixture's default).`);
43
+ }
44
+ const { width, height } = manifest;
45
+ if (width !== null && height !== null && (width % manifest.scale !== 0 || height % manifest.scale !== 0)) {
46
+ warnings.push(`frames are ${String(width)} x ${String(height)} px, not a whole number of CSS pixels at scale ${String(manifest.scale)}: ` +
47
+ `the manifest's scale does not match the pictures.`);
48
+ }
49
+ return warnings;
50
+ }
51
+ /** How many frames the warning for short holds names before it says "and N more". */
52
+ const MAX_NAMED_FRAMES = 5;
53
+ /**
54
+ * Frames that are shown for less than one GIF frame (`1 / gifFps` seconds). The GIF samples the film at its fps, so
55
+ * such a frame can be skipped and the step is missing from the GIF. Null when every frame is held long enough.
56
+ */
57
+ export function shortHoldWarning(frames, gifFps) {
58
+ const frameSeconds = 1 / gifFps;
59
+ // A hold of exactly one GIF frame is fine; the epsilon keeps 0.1 s at 10 fps from failing on float error.
60
+ const short = frames.filter((frame) => frame.hold < frameSeconds - 1e-9);
61
+ if (short.length === 0) {
62
+ return null;
63
+ }
64
+ const named = short.slice(0, MAX_NAMED_FRAMES).map((frame) => `${frame.file} (${String(frame.hold)} s)`);
65
+ const more = short.length > named.length ? ` and ${String(short.length - named.length)} more` : "";
66
+ return (`frame${short.length === 1 ? "" : "s"} ${named.join(", ")}${more} ${short.length === 1 ? "is" : "are"} held for less than one GIF frame ` +
67
+ `(${frameSeconds.toFixed(2)} s at ${String(gifFps)} fps), so the GIF can skip ${short.length === 1 ? "it" : "them"}. Hold ${short.length === 1 ? "it" : "them"} longer, or raise gif.fps.`);
68
+ }
69
+ /**
70
+ * Largest difference per colour channel (of 255) that still counts as the same pixel. Video-grade antialiasing and
71
+ * compositing noise (a caret fade, a subpixel shift of text) stays within a few shades; one plugin's loop differed by 0.9%
72
+ * of the pixels at one shade and looked identical. 8 is invisible to the eye and far below a real change (a changed
73
+ * label, a toggled control, a moved highlight differ by dozens of shades).
74
+ */
75
+ export const CHANNEL_TOLERANCE = 8;
76
+ /**
77
+ * Compares two raw RGBA buffers of `width` x `height`; null when every pixel matches within `tolerance` per channel
78
+ * (alpha included). Differences above it are reported as a box and a share, as before.
79
+ */
80
+ export function compareFrames(a, b, width, height, tolerance = CHANNEL_TOLERANCE) {
81
+ const size = width * height * 4;
82
+ if (a.length !== size || b.length !== size) {
83
+ throw new Error(`Cannot compare frames: expected ${String(size)} bytes of ${String(width)} x ${String(height)} RGBA, got ${String(a.length)} and ${String(b.length)}.`);
84
+ }
85
+ if (a.equals(b)) {
86
+ return null;
87
+ }
88
+ let minX = width;
89
+ let minY = height;
90
+ let maxX = -1;
91
+ let maxY = -1;
92
+ let count = 0;
93
+ for (let y = 0; y < height; y++) {
94
+ for (let x = 0; x < width; x++) {
95
+ const at = (y * width + x) * 4;
96
+ if (pixelsDiffer(a, b, at, tolerance)) {
97
+ count++;
98
+ minX = Math.min(minX, x);
99
+ maxX = Math.max(maxX, x);
100
+ minY = Math.min(minY, y);
101
+ maxY = Math.max(maxY, y);
102
+ }
103
+ }
104
+ }
105
+ if (count === 0) {
106
+ return null;
107
+ }
108
+ return { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1, ratio: count / (width * height) };
109
+ }
110
+ function pixelsDiffer(a, b, at, tolerance) {
111
+ for (let channel = 0; channel < 4; channel++) {
112
+ if (Math.abs((a[at + channel] ?? 0) - (b[at + channel] ?? 0)) > tolerance) {
113
+ return true;
114
+ }
115
+ }
116
+ return false;
117
+ }
118
+ export function describeLoopDifference(difference) {
119
+ const percent = difference.ratio * 100;
120
+ const share = percent < 0.1 ? "under 0.1" : percent.toFixed(1);
121
+ return (`loop does not close: the last frame differs from the first in a ${String(difference.width)} x ${String(difference.height)} px area at ` +
122
+ `(${String(difference.x)}, ${String(difference.y)}), ${share}% of the pixels. The GIF jumps when it repeats. ` +
123
+ `End the scene where it began, or set demo.loop to "off" if the jump is intended.`);
124
+ }
@@ -0,0 +1,3 @@
1
+ import type { Command } from "../cli/types.js";
2
+ export declare const demoCommand: Command;
3
+ export declare const demoCommands: readonly Command[];