obsidian-plugin-dev-kit 0.0.0-stage → 0.3.3

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,168 @@
1
+ /** Bumped when the manifest layout changes incompatibly; `opdk demo` refuses a version it does not know. */
2
+ export const MANIFEST_VERSION = 1;
3
+ /** The file name of a film's manifest inside the film's folder. */
4
+ export const MANIFEST_FILE = "manifest.json";
5
+ /** Frames per second the film is encoded at unless the film says otherwise. */
6
+ export const DEFAULT_FPS = 15;
7
+ const MAX_FPS = 60;
8
+ export function newManifest(params) {
9
+ return { version: MANIFEST_VERSION, ...params, width: null, height: null, complete: false, frames: [] };
10
+ }
11
+ /** `0001.png`: sorts in shot order up to 9999 frames, which a film of stills never approaches. */
12
+ export function frameFileName(index) {
13
+ return `${String(index + 1).padStart(4, "0")}.png`;
14
+ }
15
+ /** The most `beat()` accepts: longer is almost surely milliseconds passed where seconds are meant. */
16
+ export const MAX_BEAT_SECONDS = 60;
17
+ export function assertKind(kind) {
18
+ if (kind !== "desktop" && kind !== "phone") {
19
+ throw new Error(`film(): kind must be "desktop" or "phone", got ${JSON.stringify(kind)}.`);
20
+ }
21
+ return kind;
22
+ }
23
+ export function assertFps(fps, what = "film()") {
24
+ const value = fps ?? DEFAULT_FPS;
25
+ if (!Number.isInteger(value) || value < 1 || value > MAX_FPS) {
26
+ throw new Error(`${what}: fps must be a whole number from 1 to ${String(MAX_FPS)}, got ${String(value)}.`);
27
+ }
28
+ return value;
29
+ }
30
+ export function assertScale(scale, what) {
31
+ if (!Number.isInteger(scale) || scale < 1 || scale > 4) {
32
+ throw new Error(`${what}: scale must be a whole number from 1 to 4, got ${String(scale)}.`);
33
+ }
34
+ return scale;
35
+ }
36
+ export function assertCaptions(captions) {
37
+ if (captions === undefined) {
38
+ return [];
39
+ }
40
+ if (!Array.isArray(captions)) {
41
+ throw new Error("film(): captions must be an array of strings.");
42
+ }
43
+ const list = [];
44
+ for (const caption of captions) {
45
+ if (typeof caption !== "string") {
46
+ throw new Error("film(): captions must be an array of strings.");
47
+ }
48
+ list.push(caption);
49
+ }
50
+ return list;
51
+ }
52
+ export function assertHold(hold) {
53
+ if (!Number.isFinite(hold) || hold <= 0) {
54
+ throw new Error(`shot(): hold is how many seconds the frame stays on screen and must be above 0, got ${String(hold)}.`);
55
+ }
56
+ return hold;
57
+ }
58
+ /** The caption index of a shot, or null. An index outside `captions` is a typo in the spec, so it fails. */
59
+ export function resolveCaptionIndex(caption, captions) {
60
+ if (caption === undefined) {
61
+ return null;
62
+ }
63
+ if (!Number.isInteger(caption) || caption < 0 || caption >= captions.length) {
64
+ throw new Error(`shot(): caption ${String(caption)} is not an index of the film's captions (${String(captions.length)} given, so 0..${String(captions.length - 1)}). ` +
65
+ `Pass the texts as the captions option of film().`);
66
+ }
67
+ return caption;
68
+ }
69
+ /**
70
+ * Adds a frame. The first frame fixes the pixel size; every later one must have the same, because the encoder needs
71
+ * one size (a clip that follows an element which resizes would otherwise produce a film that cannot be encoded).
72
+ */
73
+ export function addFrame(manifest, frame, size) {
74
+ if (manifest.width !== null && manifest.height !== null && (manifest.width !== size.width || manifest.height !== size.height)) {
75
+ throw new Error(`film "${manifest.name}": frame ${String(manifest.frames.length + 1)} is ${String(size.width)} x ${String(size.height)} px but the first frame is ` +
76
+ `${String(manifest.width)} x ${String(manifest.height)}. A film needs one size: clip a fixed rectangle, or a target that does not resize.`);
77
+ }
78
+ return { ...manifest, width: size.width, height: size.height, frames: [...manifest.frames, frame] };
79
+ }
80
+ export function serializeManifest(manifest) {
81
+ return `${JSON.stringify(manifest, null, 2)}\n`;
82
+ }
83
+ function isRecord(value) {
84
+ return typeof value === "object" && value !== null && !Array.isArray(value);
85
+ }
86
+ const FRAME_FILE = /^\d{4,}\.png$/;
87
+ function parseFrame(value, index, captionCount) {
88
+ if (!isRecord(value) || typeof value.file !== "string" || typeof value.hold !== "number" || !(value.caption === null || typeof value.caption === "number")) {
89
+ throw new Error(`Film manifest: frames[${String(index)}] must be { file: string, hold: number, caption: number | null }.`);
90
+ }
91
+ // The file is joined to the film's folder by whoever reads the manifest, so it must stay a plain frame name.
92
+ if (!FRAME_FILE.test(value.file)) {
93
+ throw new Error(`Film manifest: frames[${String(index)}].file ${JSON.stringify(value.file)} must be a frame name such as 0001.png.`);
94
+ }
95
+ if (!Number.isFinite(value.hold) || value.hold <= 0) {
96
+ throw new Error(`Film manifest: frames[${String(index)}].hold must be seconds above 0, got ${String(value.hold)}.`);
97
+ }
98
+ if (value.caption !== null && (!Number.isInteger(value.caption) || value.caption < 0 || value.caption >= captionCount)) {
99
+ throw new Error(`Film manifest: frames[${String(index)}].caption ${String(value.caption)} is not an index of captions (${String(captionCount)} given).`);
100
+ }
101
+ return { file: value.file, hold: value.hold, caption: value.caption };
102
+ }
103
+ function parseSource(value) {
104
+ if (value === undefined) {
105
+ return undefined;
106
+ }
107
+ if (!isRecord(value) || typeof value.testId !== "string" || typeof value.title !== "string" || typeof value.file !== "string") {
108
+ throw new Error("Film manifest: source must be { testId: string, title: string, file: string }.");
109
+ }
110
+ return { testId: value.testId, title: value.title, file: value.file };
111
+ }
112
+ /** Reads a manifest written by `serializeManifest`; fails naming the first field that is wrong. */
113
+ export function parseFilmManifest(text) {
114
+ let value;
115
+ try {
116
+ value = JSON.parse(text);
117
+ }
118
+ catch (error) {
119
+ throw new Error(`Film manifest is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
120
+ }
121
+ if (!isRecord(value)) {
122
+ throw new Error("Film manifest must be a JSON object.");
123
+ }
124
+ if (value.version !== MANIFEST_VERSION) {
125
+ throw new Error(`Film manifest version ${JSON.stringify(value.version)} is not supported (this kit reads version ${String(MANIFEST_VERSION)}).`);
126
+ }
127
+ const { name, kind, fps, scale, theme, captions, width, height, complete, frames } = value;
128
+ if (typeof name !== "string" || typeof fps !== "number" || typeof scale !== "number" || typeof complete !== "boolean") {
129
+ throw new Error("Film manifest needs name (string), fps (number), scale (number) and complete (boolean).");
130
+ }
131
+ if (theme !== null && theme !== "light" && theme !== "dark") {
132
+ throw new Error('Film manifest: theme must be "light", "dark" or null.');
133
+ }
134
+ const captionList = [];
135
+ if (!Array.isArray(captions)) {
136
+ throw new Error("Film manifest: captions must be an array of strings.");
137
+ }
138
+ for (const caption of captions) {
139
+ if (typeof caption !== "string") {
140
+ throw new Error("Film manifest: captions must be an array of strings.");
141
+ }
142
+ captionList.push(caption);
143
+ }
144
+ if (!(width === null || typeof width === "number") || !(height === null || typeof height === "number")) {
145
+ throw new Error("Film manifest: width and height must be numbers or null.");
146
+ }
147
+ if (!Array.isArray(frames)) {
148
+ throw new Error("Film manifest: frames must be an array.");
149
+ }
150
+ if (frames.length > 0 && (typeof width !== "number" || typeof height !== "number")) {
151
+ throw new Error("Film manifest: a film with frames needs width and height (numbers).");
152
+ }
153
+ const source = parseSource(value.source);
154
+ return {
155
+ version: MANIFEST_VERSION,
156
+ name,
157
+ kind: assertKind(kind),
158
+ fps: assertFps(fps, "Film manifest"),
159
+ scale: assertScale(scale, "Film manifest"),
160
+ theme,
161
+ captions: captionList,
162
+ width,
163
+ height,
164
+ complete,
165
+ frames: frames.map((frame, index) => parseFrame(frame, index, captionList.length)),
166
+ ...(source === undefined ? {} : { source }),
167
+ };
168
+ }
@@ -0,0 +1,18 @@
1
+ /** The two colour schemes `demo.themes()` runs a scene in. */
2
+ export type ThemeMode = "light" | "dark";
3
+ /** A file-name-safe version of free text (a test title): lower case, runs of other characters become one dash. */
4
+ export declare function slugify(text: string): string;
5
+ /** Checks a name given by the spec: it ends up in a path under the output folder, so it must be one safe segment. */
6
+ export declare function assertName(name: string, what: string): string;
7
+ /**
8
+ * The text a film's default name is made of: the describe blocks and the title of the test, and the project when the
9
+ * config has more than one (the same test runs once per project and each run needs its own folder). `titlePath` is
10
+ * Playwright's `testInfo.titlePath`: the test file first, then the describe titles, then the test title.
11
+ */
12
+ export declare function defaultNameText(params: {
13
+ titlePath: readonly string[];
14
+ project: string;
15
+ projectCount: number;
16
+ }): string;
17
+ /** The name a film or still gets: the given one, or the default made of the test's title path; inside `demo.themes()` with the theme appended. */
18
+ export declare function resolveName(given: string | undefined, testTitle: string, theme: ThemeMode | null, what: string): string;
@@ -0,0 +1,44 @@
1
+ /** Longest film or still name the kit accepts; the name becomes a folder or file name. */
2
+ const MAX_NAME_LENGTH = 100;
3
+ /** One path segment: no separators, no leading dot, nothing a shell or a file system treats specially. */
4
+ const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
5
+ /** A file-name-safe version of free text (a test title): lower case, runs of other characters become one dash. */
6
+ export function slugify(text) {
7
+ return text
8
+ .toLowerCase()
9
+ .replace(/[^a-z0-9]+/g, "-")
10
+ .replace(/^-+|-+$/g, "")
11
+ .slice(0, MAX_NAME_LENGTH)
12
+ .replace(/-+$/g, "");
13
+ }
14
+ /** Checks a name given by the spec: it ends up in a path under the output folder, so it must be one safe segment. */
15
+ export function assertName(name, what) {
16
+ if (name.length > MAX_NAME_LENGTH || !NAME_PATTERN.test(name)) {
17
+ throw new Error(`${what} name ${JSON.stringify(name)} is not usable as a file name. ` +
18
+ `Use letters, digits, dots, dashes and underscores (at most ${String(MAX_NAME_LENGTH)} characters), starting with a letter or digit.`);
19
+ }
20
+ return name;
21
+ }
22
+ /**
23
+ * The text a film's default name is made of: the describe blocks and the title of the test, and the project when the
24
+ * config has more than one (the same test runs once per project and each run needs its own folder). `titlePath` is
25
+ * Playwright's `testInfo.titlePath`: the test file first, then the describe titles, then the test title.
26
+ */
27
+ export function defaultNameText(params) {
28
+ const parts = params.titlePath.slice(1);
29
+ return (params.projectCount > 1 ? [...parts, params.project] : parts).join(" ");
30
+ }
31
+ /** The name a film or still gets: the given one, or the default made of the test's title path; inside `demo.themes()` with the theme appended. */
32
+ export function resolveName(given, testTitle, theme, what) {
33
+ let base;
34
+ if (given === undefined) {
35
+ base = slugify(testTitle);
36
+ if (base === "") {
37
+ throw new Error(`The test title ${JSON.stringify(testTitle)} gives no usable ${what} name. Pass a name.`);
38
+ }
39
+ }
40
+ else {
41
+ base = assertName(given, what);
42
+ }
43
+ return theme === null ? base : `${base}-${theme}`;
44
+ }
@@ -0,0 +1,22 @@
1
+ /** The `demo` option of `createObsidianTest`. */
2
+ export interface DemoOptions {
3
+ /**
4
+ * Where films and stills are written. Relative to the directory `playwright test` runs in. Default `.opdk/demo`.
5
+ * Add `.opdk/` to the plugin's `.gitignore`: the output holds raw frames of the app and is not meant to be committed.
6
+ */
7
+ readonly outDir?: string;
8
+ /** Device pixels per CSS pixel the frames are shot at, a whole number from 1 to 4. Default 2, so frames are sharp on a 1x monitor too. */
9
+ readonly scale?: number;
10
+ /** CSS selectors that must never be in a picture. A film frame or a still fails when an element matching one is visible. */
11
+ readonly forbiddenSelectors?: readonly string[];
12
+ }
13
+ /** `DemoOptions` with defaults applied and the output folder absolute. */
14
+ export interface ResolvedDemoOptions {
15
+ readonly outDir: string;
16
+ readonly scale: number;
17
+ readonly forbiddenSelectors: readonly string[];
18
+ }
19
+ export declare const DEFAULT_DEMO_OUT_DIR = ".opdk/demo";
20
+ export declare const DEFAULT_DEMO_SCALE = 2;
21
+ /** Checks the `demo` option. Pure, like the rest of `resolveOptions`: a typo fails when `fixtures.ts` is imported. */
22
+ export declare function resolveDemoOptions(value: unknown, cwd: string): ResolvedDemoOptions;
@@ -0,0 +1,59 @@
1
+ import path from "node:path";
2
+ export const DEFAULT_DEMO_OUT_DIR = ".opdk/demo";
3
+ export const DEFAULT_DEMO_SCALE = 2;
4
+ const DEMO_KEYS = ["outDir", "scale", "forbiddenSelectors"];
5
+ const SOURCE = "createObsidianTest";
6
+ function isRecord(value) {
7
+ return typeof value === "object" && value !== null && !Array.isArray(value);
8
+ }
9
+ function own(record, key) {
10
+ return Object.hasOwn(record, key) ? record[key] : undefined;
11
+ }
12
+ /** Checks the `demo` option. Pure, like the rest of `resolveOptions`: a typo fails when `fixtures.ts` is imported. */
13
+ export function resolveDemoOptions(value, cwd) {
14
+ if (value === undefined) {
15
+ return { outDir: path.resolve(cwd, DEFAULT_DEMO_OUT_DIR), scale: DEFAULT_DEMO_SCALE, forbiddenSelectors: [] };
16
+ }
17
+ if (!isRecord(value)) {
18
+ throw new Error(`${SOURCE}: "demo" must be an object { outDir, scale, forbiddenSelectors }.`);
19
+ }
20
+ for (const key of Object.keys(value)) {
21
+ if (!DEMO_KEYS.includes(key)) {
22
+ throw new Error(`${SOURCE}: unknown key "demo.${key}". Known keys: ${DEMO_KEYS.join(", ")}.`);
23
+ }
24
+ }
25
+ let outDir = DEFAULT_DEMO_OUT_DIR;
26
+ const givenOutDir = own(value, "outDir");
27
+ if (givenOutDir !== undefined) {
28
+ if (typeof givenOutDir !== "string" || givenOutDir === "") {
29
+ throw new Error(`${SOURCE}: "demo.outDir" must be a non-empty string.`);
30
+ }
31
+ outDir = givenOutDir;
32
+ }
33
+ let scale = DEFAULT_DEMO_SCALE;
34
+ const givenScale = own(value, "scale");
35
+ if (givenScale !== undefined) {
36
+ if (typeof givenScale !== "number" || !Number.isInteger(givenScale) || givenScale < 1 || givenScale > 4) {
37
+ throw new Error(`${SOURCE}: "demo.scale" must be a whole number from 1 to 4.`);
38
+ }
39
+ scale = givenScale;
40
+ }
41
+ const selectors = own(value, "forbiddenSelectors");
42
+ const forbiddenSelectors = [];
43
+ if (selectors !== undefined) {
44
+ if (!Array.isArray(selectors)) {
45
+ throw new Error(`${SOURCE}: "demo.forbiddenSelectors" must be an array of non-empty CSS selectors.`);
46
+ }
47
+ for (const selector of selectors) {
48
+ if (typeof selector !== "string" || selector.trim() === "") {
49
+ throw new Error(`${SOURCE}: "demo.forbiddenSelectors" must be an array of non-empty CSS selectors.`);
50
+ }
51
+ forbiddenSelectors.push(selector);
52
+ }
53
+ }
54
+ return {
55
+ outDir: path.resolve(cwd, outDir),
56
+ scale,
57
+ forbiddenSelectors,
58
+ };
59
+ }
@@ -0,0 +1,27 @@
1
+ /** The file in a film's folder that says which test wrote the film in which run. */
2
+ export declare const OWNER_FILE = "owner.json";
3
+ /** The folder of stills under the demo output folder (`<outDir>/stills/<name>.png`). */
4
+ export declare const STILLS_DIR = "stills";
5
+ /** Folder under the output folder with one such file per still, so `stills/` holds pictures only. */
6
+ export declare const STILL_OWNERS_DIR: string;
7
+ /** Who wrote a film or a still: the test and the run (one `playwright test` invocation). */
8
+ export interface Owner {
9
+ readonly testId: string;
10
+ readonly runId: string;
11
+ /** For the message only. */
12
+ readonly title: string;
13
+ }
14
+ export declare function serializeOwner(owner: Owner): string;
15
+ /** Reads a marker; text that is not a marker gives null, so a damaged file never blocks a retake. */
16
+ export declare function parseOwner(text: string): Owner | null;
17
+ /**
18
+ * Two tests that end up with the same name would silently replace each other's pictures; the run then publishes
19
+ * whichever finished last. A marker from an earlier run is a retake and is replaced; so is one from the same test (a retry).
20
+ */
21
+ export declare function assertNotOwnedByAnotherTest(existing: Owner | null, current: Owner, what: string): void;
22
+ /** Fails when another test of this run owns the film folder `dir`. Call before the folder is emptied. */
23
+ export declare function assertFilmFree(dir: string, current: Owner, what: string): void;
24
+ export declare function writeFilmOwner(dir: string, owner: Owner): void;
25
+ /** Fails when another test of this run wrote the still `name` under the output folder `outDir`. */
26
+ export declare function assertStillFree(outDir: string, name: string, current: Owner, what: string): void;
27
+ export declare function writeStillOwner(outDir: string, name: string, owner: Owner): void;
@@ -0,0 +1,65 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+ /** The file in a film's folder that says which test wrote the film in which run. */
4
+ export const OWNER_FILE = "owner.json";
5
+ /** The folder of stills under the demo output folder (`<outDir>/stills/<name>.png`). */
6
+ export const STILLS_DIR = "stills";
7
+ /** Folder under the output folder with one such file per still, so `stills/` holds pictures only. */
8
+ export const STILL_OWNERS_DIR = path.join(".owners", "stills");
9
+ export function serializeOwner(owner) {
10
+ return `${JSON.stringify(owner, null, 2)}\n`;
11
+ }
12
+ /** Reads a marker; text that is not a marker gives null, so a damaged file never blocks a retake. */
13
+ export function parseOwner(text) {
14
+ let value;
15
+ try {
16
+ value = JSON.parse(text);
17
+ }
18
+ catch {
19
+ return null;
20
+ }
21
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
22
+ return null;
23
+ }
24
+ const { testId, runId, title } = value;
25
+ return typeof testId === "string" && typeof runId === "string" && typeof title === "string" ? { testId, runId, title } : null;
26
+ }
27
+ /**
28
+ * Two tests that end up with the same name would silently replace each other's pictures; the run then publishes
29
+ * whichever finished last. A marker from an earlier run is a retake and is replaced; so is one from the same test (a retry).
30
+ */
31
+ export function assertNotOwnedByAnotherTest(existing, current, what) {
32
+ if (existing !== null && existing.runId === current.runId && existing.testId !== current.testId) {
33
+ throw new Error(`${what} was already written in this run by another test ("${existing.title}"). ` +
34
+ `Two tests with the same name would replace each other's pictures; pass a different name in one of them.`);
35
+ }
36
+ }
37
+ function readOwner(file) {
38
+ let text;
39
+ try {
40
+ text = fs.readFileSync(file, "utf8");
41
+ }
42
+ catch (error) {
43
+ if (error instanceof Error && "code" in error && error.code === "ENOENT") {
44
+ return null;
45
+ }
46
+ throw error;
47
+ }
48
+ return parseOwner(text);
49
+ }
50
+ /** Fails when another test of this run owns the film folder `dir`. Call before the folder is emptied. */
51
+ export function assertFilmFree(dir, current, what) {
52
+ assertNotOwnedByAnotherTest(readOwner(path.join(dir, OWNER_FILE)), current, what);
53
+ }
54
+ export function writeFilmOwner(dir, owner) {
55
+ fs.writeFileSync(path.join(dir, OWNER_FILE), serializeOwner(owner));
56
+ }
57
+ /** Fails when another test of this run wrote the still `name` under the output folder `outDir`. */
58
+ export function assertStillFree(outDir, name, current, what) {
59
+ assertNotOwnedByAnotherTest(readOwner(path.join(outDir, STILL_OWNERS_DIR, `${name}.json`)), current, what);
60
+ }
61
+ export function writeStillOwner(outDir, name, owner) {
62
+ const dir = path.join(outDir, STILL_OWNERS_DIR);
63
+ fs.mkdirSync(dir, { recursive: true });
64
+ fs.writeFileSync(path.join(dir, `${name}.json`), serializeOwner(owner));
65
+ }
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Functions Playwright serializes and runs inside Obsidian, for the `demo` fixture. Like `../helpers/page-scripts.ts`,
3
+ * each one must be self-contained: only its source text crosses into the page. The kit's TypeScript has no DOM types,
4
+ * hence the small interfaces below.
5
+ */
6
+ /** The overlay's commands, as the page API takes them. */
7
+ export type OverlayCall = {
8
+ method: "caption";
9
+ arg: string | null;
10
+ } | {
11
+ method: "pointer";
12
+ arg: "cursor" | "tap";
13
+ } | {
14
+ method: "hidePointer";
15
+ arg: null;
16
+ } | {
17
+ method: "cursorEnabled";
18
+ arg: boolean;
19
+ } | {
20
+ method: "clean";
21
+ arg: {
22
+ statusBar: boolean;
23
+ tabHeaders: boolean;
24
+ };
25
+ };
26
+ /**
27
+ * The look of the overlays and of the freeze, in one place so the tests can check what the page gets. No transition
28
+ * or animation on the overlays: a CDP capture does not wait for them (a tap dot caught mid-shrink showed in a spike
29
+ * frame), so every state change must land at once.
30
+ */
31
+ export declare const OVERLAY_CSS: string;
32
+ /** The arrow of the demo cursor. */
33
+ export declare const CURSOR_SVG: string;
34
+ /**
35
+ * Init script of the Obsidian window (`context.addInitScript`), also run once in the page that is already up. It
36
+ * draws the cursor, the tap dot and the caption bar into `<html>`, outside Obsidian's `<body>`, above every modal. The
37
+ * state (pointer position and kind, caption, hidden UI parts) lives in `sessionStorage`, so a document that replaces
38
+ * this one (`reload()`, `mobile()`, `desktop()`) restores it. Captions go in through `textContent`: markup shows literally.
39
+ * Idempotent. The look comes in as the argument because only the function's own source text reaches the page.
40
+ */
41
+ export declare function installOverlay(assets: {
42
+ cssText: string;
43
+ cursorSvg: string;
44
+ }): void;
45
+ /** Runs one overlay command in the page. False when the overlay is not there (the init script did not run in this document). */
46
+ export declare function runOverlay(call: OverlayCall): boolean;
47
+ export interface FreezeResult {
48
+ /** Animations and transitions that were running and were jumped to their end. */
49
+ finished: number;
50
+ /** Endless animations (a caret blink, a spinner) that were paused until `releaseShot()`. */
51
+ paused: number;
52
+ }
53
+ /**
54
+ * Makes the page hold still for one capture. A CDP screenshot does not wait for anything, so: the class
55
+ * `opdk-shooting` ends CSS transitions at once and hides the caret; running animations jump to their end (an endless
56
+ * one cannot finish, so it is paused and `releaseShot()` plays it again; a finite one that finished stays finished);
57
+ * two frames are awaited so the result is drawn, with a timer as the fallback for a window that draws no frames.
58
+ * `releaseShot()` removes the class.
59
+ */
60
+ export declare function freezeForShot(): Promise<FreezeResult>;
61
+ /** Ends the freeze: removes the class and plays the endless animations that `freezeForShot()` paused. */
62
+ export declare function releaseShot(): void;
63
+ /** Whether the focused element takes typed text: a text input, a textarea or a contenteditable (Obsidian's editor is one). */
64
+ export declare function hasEditableFocus(): boolean;
65
+ /** The window's size in CSS pixels and its pixel ratio (the emulated one when device metrics are overridden). */
66
+ export interface Viewport {
67
+ width: number;
68
+ height: number;
69
+ scale: number;
70
+ }
71
+ export declare function readViewport(): Viewport;
72
+ export declare function hasViewport(want: Viewport): boolean;
73
+ /**
74
+ * The parts of the UI that Obsidian itself can hide. True means shown. The settings are saved at once: Obsidian writes
75
+ * them on a delay, and `reload()` reloads without saving, so a reload right after would bring the old values back
76
+ * (found in the kit's live spec). Returns false when this Obsidian cannot be configured.
77
+ */
78
+ export declare function applyObsidianUi(show: {
79
+ showRibbon: boolean;
80
+ showViewHeader: boolean;
81
+ showInlineTitle: boolean;
82
+ }): Promise<boolean>;