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,439 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+ import { isMobileApplied } from "../helpers/page-scripts.js";
4
+ import { assertPadding, pixelSize, resolveClip } from "./clip.js";
5
+ import { assertFrameSize } from "./png.js";
6
+ import { addFrame, assertCaptions, assertFps, assertHold, assertKind, assertScale, frameFileName, MANIFEST_FILE, MAX_BEAT_SECONDS, newManifest, resolveCaptionIndex, serializeManifest, } from "./manifest.js";
7
+ import { resolveName } from "./names.js";
8
+ import { assertFilmFree, assertStillFree, STILLS_DIR, writeFilmOwner, writeStillOwner } from "./ownership.js";
9
+ import { applyObsidianUi, CURSOR_SVG, freezeForShot, hasEditableFocus, hasViewport, installOverlay, OVERLAY_CSS, readViewport, releaseShot, runOverlay, } from "./page-scripts.js";
10
+ import { presetViewport } from "./presets.js";
11
+ import { resolveStillPublishing, writeStillPublishing } from "./still-options.js";
12
+ import { assertCaptureAllowed, forbiddenMessage, mergeSelectors } from "./privacy.js";
13
+ /** Mouse positions between the old and the new place of the cursor, so a viewer can follow it. */
14
+ const CURSOR_STEPS = 14;
15
+ const DEFAULT_TYPE_DELAY_MS = 40;
16
+ /** Per key press, on top of the delay: Playwright's own work for one key. */
17
+ const TYPING_SLACK_MS = 50;
18
+ const POLL_MS = 50;
19
+ const CLEAN_UI_KEYS = ["ribbon", "statusBar", "tabHeaders", "viewHeader", "inlineTitle", "sidebars"];
20
+ const FILMS_DIR = "films";
21
+ function isLocator(target) {
22
+ return "boundingBox" in target;
23
+ }
24
+ function reason(error) {
25
+ return error instanceof Error ? error.message.split("\n")[0] ?? "" : String(error);
26
+ }
27
+ /** Runs `action`; returns what it threw, or undefined. For cleanup that must not hide the error that made it necessary. */
28
+ async function attempt(action) {
29
+ try {
30
+ await action();
31
+ return undefined;
32
+ }
33
+ catch (error) {
34
+ return { error };
35
+ }
36
+ }
37
+ function errorText(error) {
38
+ return error instanceof Error ? error.message : String(error);
39
+ }
40
+ function assertSettle(settle, what) {
41
+ if (settle !== undefined && typeof settle !== "boolean") {
42
+ throw new Error(`${what}: settle must be true or false, got ${JSON.stringify(settle)}.`);
43
+ }
44
+ return settle ?? false;
45
+ }
46
+ function assertCursor(cursor, what) {
47
+ if (cursor !== undefined && typeof cursor !== "boolean") {
48
+ throw new Error(`${what}: cursor must be true (show the arrow) or false (hide it), got ${JSON.stringify(cursor)}.`);
49
+ }
50
+ return cursor ?? true;
51
+ }
52
+ function assertClipPadding(clip, padding) {
53
+ assertPadding(padding);
54
+ if (padding > 0 && clip === undefined) {
55
+ throw new Error("padding is the margin around a clip and needs a clip.");
56
+ }
57
+ }
58
+ /** The `demo` fixture's functions, bound to one test's window. Everything that waits polls state; the only fixed delay is `beat()`. */
59
+ export function createDemo(deps) {
60
+ const { win, options } = deps;
61
+ const owner = { testId: deps.source.testId, runId: deps.runId, title: deps.source.title };
62
+ const films = new Map();
63
+ let theme = null;
64
+ let overlayReady;
65
+ /** What the page's overlay was last told about the cursor arrow; it is shown until a film asks otherwise. */
66
+ let cursorEnabled = true;
67
+ /** Installs the overlay in every later document (reload, mobile, desktop) and in the one that is up now. */
68
+ function ensureOverlay() {
69
+ overlayReady ??= (async () => {
70
+ const assets = { cssText: OVERLAY_CSS, cursorSvg: CURSOR_SVG };
71
+ await win.context().addInitScript(installOverlay, assets);
72
+ await win.evaluate(installOverlay, assets);
73
+ })();
74
+ return overlayReady;
75
+ }
76
+ async function overlay(call) {
77
+ await ensureOverlay();
78
+ if (!(await win.evaluate(runOverlay, call))) {
79
+ throw new Error(`The demo overlay is missing from this document (${call.method}). Its init script runs in every document of the window; was the window replaced?`);
80
+ }
81
+ }
82
+ /** Switches the cursor arrow for the pictures that follow; a call that changes nothing sends nothing. */
83
+ async function setCursor(enabled) {
84
+ if (enabled !== cursorEnabled) {
85
+ await overlay({ method: "cursorEnabled", arg: enabled });
86
+ cursorEnabled = enabled;
87
+ }
88
+ }
89
+ async function waitVisible(target, what) {
90
+ try {
91
+ await target.waitFor({ state: "visible", timeout: deps.uiTimeoutMs });
92
+ }
93
+ catch (error) {
94
+ throw new Error(`${what}: ${String(target)} was not visible within ${String(deps.uiTimeoutMs)} ms (${reason(error)}). ` +
95
+ `The demo helpers fail on a missing target instead of skipping it; check the selector and the state of the app.`, { cause: error });
96
+ }
97
+ }
98
+ async function targetRect(target, what) {
99
+ if (!isLocator(target)) {
100
+ return target;
101
+ }
102
+ await waitVisible(target, what);
103
+ const box = await target.boundingBox();
104
+ if (box === null) {
105
+ throw new Error(`${what}: ${String(target)} has no bounding box although it is visible. Is it inside an iframe?`);
106
+ }
107
+ return box;
108
+ }
109
+ /** Sets the window's CSS size and pixel ratio through the shared session; returns what was there, to put it back. */
110
+ async function setViewport(want) {
111
+ const reported = await win.evaluate(readViewport);
112
+ // Playwright's page.screenshot() drops the override from the page, but the session still counts it. The size it
113
+ // last set (a phone, after obsidian.mobile()) is what the window is meant to have, not what the page reports now.
114
+ const meant = deps.deviceMetrics.last();
115
+ const before = meant === undefined ? reported : { width: meant.width, height: meant.height, scale: meant.deviceScaleFactor };
116
+ const target = { width: want.width ?? before.width, height: want.height ?? before.height, scale: want.scale };
117
+ if (target.width === reported.width && target.height === reported.height && target.scale === reported.scale) {
118
+ return before;
119
+ }
120
+ // Chromium drops the override after Playwright's page.screenshot() (it captures beyond the viewport). The tracker
121
+ // clears the session's own first when a set would repeat its last one, which Chromium would ignore.
122
+ // Seen in the K-026 trial on a 1x display, where the next shot failed with "did not become ... at scale 2".
123
+ const override = (size) => deps.deviceMetrics.set({ width: size.width, height: size.height, deviceScaleFactor: size.scale, mobile: false });
124
+ try {
125
+ await override(target);
126
+ try {
127
+ await win.waitForFunction(hasViewport, target, { polling: POLL_MS, timeout: deps.uiTimeoutMs });
128
+ }
129
+ catch (error) {
130
+ throw new Error(`The window did not become ${String(target.width)} x ${String(target.height)} at scale ${String(target.scale)} within ${String(deps.uiTimeoutMs)} ms after the device metrics override.`, { cause: error });
131
+ }
132
+ }
133
+ catch (error) {
134
+ // The window must not stay resized after a failed attempt; the first error is the one to report.
135
+ const restoreFailure = await attempt(() => override(before));
136
+ if (restoreFailure !== undefined) {
137
+ throw new Error(`${errorText(error)} Putting the previous size back also failed (${reason(restoreFailure.error)}); the window may still be resized.`, { cause: error });
138
+ }
139
+ throw error;
140
+ }
141
+ return before;
142
+ }
143
+ async function assertNoForbidden(selectors, what) {
144
+ for (const selector of selectors) {
145
+ if ((await win.locator(selector).filter({ visible: true }).count()) > 0) {
146
+ throw new Error(forbiddenMessage(selector, what));
147
+ }
148
+ }
149
+ }
150
+ /** The frozen part of a shot: freeze, find the area, check the forbidden selectors, capture, check the size, thaw. */
151
+ async function captureFrozen(params) {
152
+ try {
153
+ // Inside the try: a freeze that fails half way has already set the class, and the release must run.
154
+ await win.evaluate(freezeForShot);
155
+ const viewport = await win.evaluate(readViewport);
156
+ const rect = params.clip === undefined ? undefined : resolveClip(await targetRect(params.clip, params.what), params.padding, viewport, params.what);
157
+ await assertNoForbidden(params.forbidden, params.what);
158
+ const session = await deps.cdp();
159
+ const { data } = await session.send("Page.captureScreenshot", rect === undefined ? { format: "png" } : { format: "png", clip: { ...rect, scale: 1 } });
160
+ const png = Buffer.from(data, "base64");
161
+ return { png, size: assertFrameSize(png, pixelSize(rect ?? viewport, params.scale), params.scale, params.what) };
162
+ }
163
+ finally {
164
+ await win.evaluate(releaseShot);
165
+ }
166
+ }
167
+ async function capture(params) {
168
+ await ensureOverlay();
169
+ const before = await setViewport({ width: params.preset?.cssWidth, height: params.preset?.cssHeight, scale: params.scale });
170
+ let captured;
171
+ try {
172
+ // After the preset's resize, so the reflow it causes is waited for, and before the freeze, which ends animations.
173
+ if (params.settle) {
174
+ await deps.settle();
175
+ }
176
+ captured = await captureFrozen(params);
177
+ }
178
+ catch (error) {
179
+ // A preset resizes the window for one picture; put it back, and keep the shot's error when that fails too.
180
+ const restoreFailure = params.preset === undefined ? undefined : await attempt(() => setViewport(before));
181
+ if (restoreFailure !== undefined) {
182
+ throw new Error(`${errorText(error)} Putting the window back also failed: ${errorText(restoreFailure.error)}`, { cause: error });
183
+ }
184
+ throw error;
185
+ }
186
+ // A film keeps its scale from frame to frame.
187
+ if (params.preset !== undefined) {
188
+ await setViewport(before);
189
+ }
190
+ return captured;
191
+ }
192
+ function film(filmOptions) {
193
+ const kind = assertKind(filmOptions.kind);
194
+ const fps = assertFps(filmOptions.fps);
195
+ const scale = assertScale(filmOptions.scale ?? options.scale, "film()");
196
+ const cursor = assertCursor(filmOptions.cursor, "film()");
197
+ const captions = assertCaptions(filmOptions.captions);
198
+ const padding = filmOptions.padding ?? 0;
199
+ assertClipPadding(filmOptions.clip, padding);
200
+ const name = resolveName(filmOptions.name, deps.testTitle, theme, "film");
201
+ assertCaptureAllowed({ source: deps.seedVaultSource, seedVault: deps.seedVault, cwd: deps.cwd, allowForeignVault: filmOptions.allowForeignVault, action: `film "${name}"` });
202
+ if (films.has(name)) {
203
+ throw new Error(`film "${name}" was already started in this test. Pass a name to film() for each film; a retake is a new run of the test, which replaces the frames.`);
204
+ }
205
+ const dir = path.join(options.outDir, FILMS_DIR, name);
206
+ assertFilmFree(dir, owner, `film "${name}"`);
207
+ // A retake replaces the film: frames of an earlier run must not survive next to the new ones.
208
+ fs.rmSync(dir, { recursive: true, force: true });
209
+ fs.mkdirSync(dir, { recursive: true });
210
+ writeFilmOwner(dir, owner);
211
+ const state = {
212
+ manifest: newManifest({ name, kind, fps, scale, theme, captions, source: deps.source }),
213
+ dir,
214
+ clip: filmOptions.clip,
215
+ padding,
216
+ forbidden: mergeSelectors(options.forbiddenSelectors, filmOptions.forbiddenSelectors),
217
+ cursor,
218
+ kindChecked: false,
219
+ };
220
+ films.set(name, state);
221
+ const writeManifest = () => {
222
+ fs.writeFileSync(path.join(dir, MANIFEST_FILE), serializeManifest(state.manifest));
223
+ };
224
+ writeManifest();
225
+ return {
226
+ name,
227
+ dir,
228
+ shot: async (shotOptions) => {
229
+ const hold = assertHold(shotOptions.hold);
230
+ const caption = resolveCaptionIndex(shotOptions.caption, state.manifest.captions);
231
+ const index = state.manifest.frames.length;
232
+ const what = `film "${name}", frame ${String(index + 1)}`;
233
+ if (!state.kindChecked) {
234
+ const mobile = await win.evaluate(isMobileApplied, true);
235
+ if (mobile !== (kind === "phone")) {
236
+ const fix = mobile
237
+ ? "Call obsidian.desktop() first, or make this a phone film."
238
+ : "Call obsidian.mobile() first (and open the note again: the mobile workspace starts empty), or make this a desktop film.";
239
+ throw new Error(`${what}: the film is a ${kind} film but the window ${mobile ? "is" : "is not"} in the mobile emulation. ${fix}`);
240
+ }
241
+ state.kindChecked = true;
242
+ }
243
+ const clip = shotOptions.clip ?? state.clip;
244
+ const padding = shotOptions.padding ?? state.padding;
245
+ assertClipPadding(clip, padding);
246
+ const settle = assertSettle(shotOptions.settle, what);
247
+ await setCursor(state.cursor);
248
+ const { png, size } = await capture({ what, scale, preset: undefined, clip, padding, forbidden: state.forbidden, settle });
249
+ const frame = { file: frameFileName(index), hold, caption };
250
+ // Checks the size against the first frame before anything is written.
251
+ const next = addFrame(state.manifest, frame, size);
252
+ fs.writeFileSync(path.join(dir, frame.file), png);
253
+ state.manifest = next;
254
+ writeManifest();
255
+ return frame;
256
+ },
257
+ };
258
+ }
259
+ async function still(name, stillOptions = {}) {
260
+ const fileName = resolveName(name, deps.testTitle, theme, "still");
261
+ assertCaptureAllowed({ source: deps.seedVaultSource, seedVault: deps.seedVault, cwd: deps.cwd, allowForeignVault: stillOptions.allowForeignVault, action: `still "${fileName}"` });
262
+ const stillsDir = path.join(options.outDir, STILLS_DIR);
263
+ assertStillFree(options.outDir, fileName, owner, `still "${fileName}"`);
264
+ const preset = stillOptions.preset === undefined ? undefined : presetViewport(stillOptions.preset);
265
+ if (preset !== undefined && (stillOptions.clip !== undefined || stillOptions.scale !== undefined)) {
266
+ throw new Error(`still "${fileName}": the preset ${String(stillOptions.preset)} fixes the picture size, so it cannot be combined with clip or scale.`);
267
+ }
268
+ const padding = stillOptions.padding ?? 0;
269
+ assertClipPadding(stillOptions.clip, padding);
270
+ const scale = preset?.scale ?? assertScale(stillOptions.scale ?? options.scale, `still "${fileName}"`);
271
+ const settle = assertSettle(stillOptions.settle, `still "${fileName}"`);
272
+ const cursor = assertCursor(stillOptions.cursor, `still "${fileName}"`);
273
+ const publishing = resolveStillPublishing(stillOptions, `still "${fileName}"`);
274
+ // Set for every picture, so a still that hides the arrow does not leave it hidden for the next film or still.
275
+ await setCursor(cursor);
276
+ const { png, size } = await capture({
277
+ what: `still "${fileName}"`,
278
+ scale,
279
+ preset,
280
+ clip: stillOptions.clip,
281
+ padding,
282
+ forbidden: mergeSelectors(options.forbiddenSelectors, stillOptions.forbiddenSelectors),
283
+ settle,
284
+ });
285
+ fs.mkdirSync(stillsDir, { recursive: true });
286
+ const file = path.join(stillsDir, `${fileName}.png`);
287
+ fs.writeFileSync(file, png);
288
+ writeStillOwner(options.outDir, fileName, owner);
289
+ // Always written, so a retake with other options replaces what the earlier take asked for.
290
+ writeStillPublishing(options.outDir, fileName, publishing);
291
+ return { file, width: size.width, height: size.height };
292
+ }
293
+ async function moveAndClick(target) {
294
+ await overlay({ method: "pointer", arg: "cursor" });
295
+ await waitVisible(target, "moveAndClick()");
296
+ await target.scrollIntoViewIfNeeded({ timeout: deps.uiTimeoutMs });
297
+ const box = await target.boundingBox();
298
+ if (box === null) {
299
+ throw new Error(`moveAndClick(): ${String(target)} has no bounding box although it is visible.`);
300
+ }
301
+ await win.mouse.move(box.x + box.width / 2, box.y + box.height / 2, { steps: CURSOR_STEPS });
302
+ await target.click({ timeout: deps.uiTimeoutMs });
303
+ }
304
+ async function tap(target, tapOptions = {}) {
305
+ await overlay({ method: "pointer", arg: "tap" });
306
+ await waitVisible(target, "tap()");
307
+ // hover() scrolls, checks that the target is not covered, and moves the mouse to its centre.
308
+ await target.hover({ timeout: deps.uiTimeoutMs });
309
+ await win.mouse.down();
310
+ try {
311
+ await tapOptions.whilePressed?.();
312
+ }
313
+ finally {
314
+ // The finger goes up and the dot goes away even when the callback failed: a dot left behind shows in the next frame.
315
+ try {
316
+ await win.mouse.up();
317
+ }
318
+ finally {
319
+ await overlay({ method: "hidePointer", arg: null });
320
+ }
321
+ }
322
+ }
323
+ async function typeSlowly(first, second, third) {
324
+ const target = typeof first === "string" ? undefined : first;
325
+ const text = typeof first === "string" ? first : second;
326
+ const typeOptions = typeof first === "string" ? second : third;
327
+ if (typeof text !== "string" || (typeOptions !== undefined && typeof typeOptions === "string")) {
328
+ throw new Error("typeSlowly(): pass the text, or a target and the text.");
329
+ }
330
+ const delay = typeOptions?.delayMs ?? DEFAULT_TYPE_DELAY_MS;
331
+ if (!Number.isFinite(delay) || delay < 0) {
332
+ throw new Error(`typeSlowly(): delayMs must be a number of milliseconds from 0, got ${String(delay)}.`);
333
+ }
334
+ if (target === undefined) {
335
+ if (!(await win.evaluate(hasEditableFocus))) {
336
+ throw new Error("typeSlowly(text): nothing editable has focus, so the keys would go nowhere. Pass the target, typeSlowly(locator, text), or focus an input or the editor first.");
337
+ }
338
+ await win.keyboard.type(text, { delay });
339
+ return;
340
+ }
341
+ await moveAndClick(target);
342
+ await target.pressSequentially(text, { delay, timeout: deps.uiTimeoutMs + text.length * (delay + TYPING_SLACK_MS) });
343
+ }
344
+ async function beat(seconds) {
345
+ if (!Number.isFinite(seconds) || seconds < 0) {
346
+ throw new Error(`beat(): seconds must be a number from 0, got ${String(seconds)}.`);
347
+ }
348
+ if (seconds > MAX_BEAT_SECONDS) {
349
+ throw new Error(`beat(): ${String(seconds)} seconds is more than ${String(MAX_BEAT_SECONDS)}. beat() takes seconds, not milliseconds (an earlier harness's beat took milliseconds); ` +
350
+ `did you mean beat(${String(seconds / 1000)})?`);
351
+ }
352
+ await win.waitForTimeout(seconds * 1000);
353
+ }
354
+ async function cleanUi(cleanOptions = {}) {
355
+ for (const key of Object.keys(cleanOptions)) {
356
+ if (!CLEAN_UI_KEYS.includes(key)) {
357
+ throw new Error(`cleanUi(): unknown option "${key}". Known options: ${CLEAN_UI_KEYS.join(", ")}.`);
358
+ }
359
+ }
360
+ const hide = {
361
+ ribbon: cleanOptions.ribbon ?? true,
362
+ statusBar: cleanOptions.statusBar ?? true,
363
+ tabHeaders: cleanOptions.tabHeaders ?? true,
364
+ viewHeader: cleanOptions.viewHeader ?? true,
365
+ inlineTitle: cleanOptions.inlineTitle ?? true,
366
+ };
367
+ const sidebars = cleanOptions.sidebars ?? true;
368
+ for (const [key, value] of Object.entries({ ...hide, sidebars })) {
369
+ if (typeof value !== "boolean") {
370
+ throw new Error(`cleanUi(): ${key} must be true (hide) or false (show), got ${JSON.stringify(value)}.`);
371
+ }
372
+ }
373
+ await ensureOverlay();
374
+ const applied = await win.evaluate(applyObsidianUi, { showRibbon: !hide.ribbon, showViewHeader: !hide.viewHeader, showInlineTitle: !hide.inlineTitle });
375
+ if (!applied) {
376
+ throw new Error("cleanUi(): this Obsidian has no app.vault.setConfig. The helper was verified on Obsidian 1.14.5.");
377
+ }
378
+ await overlay({ method: "clean", arg: { statusBar: hide.statusBar, tabHeaders: hide.tabHeaders } });
379
+ if (sidebars) {
380
+ await deps.collapseSidebars();
381
+ }
382
+ }
383
+ async function freezeTime(date) {
384
+ const at = new Date(date);
385
+ if (Number.isNaN(at.getTime())) {
386
+ throw new Error(`freezeTime(): ${String(date)} is not a date. Pass a Date, an ISO string such as "2026-03-14T09:26:00", or a timestamp.`);
387
+ }
388
+ // setFixedTime, not clock.install: an installed clock that is paused stops every timer in Obsidian.
389
+ await win.clock.setFixedTime(at);
390
+ }
391
+ async function themes(modes, scene) {
392
+ if (theme !== null) {
393
+ throw new Error(`themes() cannot be nested: the scene of the ${theme} run called it again.`);
394
+ }
395
+ // A spec in plain JavaScript can pass anything.
396
+ const given = modes;
397
+ if (given.length === 0 || new Set(given).size !== given.length || given.some((mode) => mode !== "light" && mode !== "dark")) {
398
+ throw new Error(`themes(): pass "light", "dark" or both, each once; got ${JSON.stringify(modes)}.`);
399
+ }
400
+ for (const mode of modes) {
401
+ await deps.setTheme({ mode });
402
+ theme = mode;
403
+ try {
404
+ await scene(mode);
405
+ }
406
+ finally {
407
+ theme = null;
408
+ }
409
+ }
410
+ }
411
+ const demo = {
412
+ film,
413
+ still,
414
+ moveAndClick,
415
+ tap,
416
+ typeSlowly,
417
+ beat,
418
+ caption: (text) => overlay({ method: "caption", arg: text }),
419
+ hideCursor: () => overlay({ method: "hidePointer", arg: null }),
420
+ cleanUi,
421
+ freezeTime,
422
+ themes,
423
+ };
424
+ return {
425
+ demo,
426
+ finish: ({ status }) => {
427
+ // A test marked test.fail() "fails as expected" and stays unfinished too: only a real pass completes a film.
428
+ if (status !== "passed") {
429
+ return;
430
+ }
431
+ for (const state of films.values()) {
432
+ if (state.manifest.frames.length > 0) {
433
+ state.manifest = { ...state.manifest, complete: true };
434
+ fs.writeFileSync(path.join(state.dir, MANIFEST_FILE), serializeManifest(state.manifest));
435
+ }
436
+ }
437
+ },
438
+ };
439
+ }
@@ -0,0 +1,76 @@
1
+ import type { Size } from "./clip.js";
2
+ import type { ThemeMode } from "./names.js";
3
+ /** Bumped when the manifest layout changes incompatibly; `opdk demo` refuses a version it does not know. */
4
+ export declare const MANIFEST_VERSION = 1;
5
+ /** The file name of a film's manifest inside the film's folder. */
6
+ export declare const MANIFEST_FILE = "manifest.json";
7
+ /** Frames per second the film is encoded at unless the film says otherwise. */
8
+ export declare const DEFAULT_FPS = 15;
9
+ export type FilmKind = "desktop" | "phone";
10
+ /** One picture of a film and how long the viewer sees it. */
11
+ export interface FilmFrame {
12
+ /** Relative to the film's folder. */
13
+ readonly file: string;
14
+ /** Seconds. */
15
+ readonly hold: number;
16
+ /** Index into `captions`, or null when the frame has no caption beside it. */
17
+ readonly caption: number | null;
18
+ }
19
+ /** The test that recorded a film, so a later step can list the films whose test no longer exists. */
20
+ export interface FilmSource {
21
+ /** Playwright's id of the test. */
22
+ readonly testId: string;
23
+ /** Describe titles and test title, joined with spaces. */
24
+ readonly title: string;
25
+ /** The spec file, relative to the directory `playwright test` ran in, with forward slashes. */
26
+ readonly file: string;
27
+ }
28
+ /** What a film recorded, as written to `<outDir>/films/<name>/manifest.json`. */
29
+ export interface FilmManifest {
30
+ readonly version: typeof MANIFEST_VERSION;
31
+ readonly name: string;
32
+ readonly kind: FilmKind;
33
+ readonly fps: number;
34
+ /** Device pixels per CSS pixel the frames were shot at. */
35
+ readonly scale: number;
36
+ /** The colour scheme `demo.themes()` shot this film in, or null outside it. */
37
+ readonly theme: ThemeMode | null;
38
+ /** Text for the caption list a composed phone film shows beside the phone; not drawn into the frames. */
39
+ readonly captions: readonly string[];
40
+ /** Pixel size of every frame; null until the first frame is shot. */
41
+ readonly width: number | null;
42
+ readonly height: number | null;
43
+ /** False while the film records and when its test failed, so a half film is never encoded by mistake. */
44
+ readonly complete: boolean;
45
+ readonly frames: readonly FilmFrame[];
46
+ /** The recording test; absent in a manifest written by an older kit. */
47
+ readonly source?: FilmSource;
48
+ }
49
+ export declare function newManifest(params: {
50
+ name: string;
51
+ kind: FilmKind;
52
+ fps: number;
53
+ scale: number;
54
+ theme: ThemeMode | null;
55
+ captions: readonly string[];
56
+ source?: FilmSource;
57
+ }): FilmManifest;
58
+ /** `0001.png`: sorts in shot order up to 9999 frames, which a film of stills never approaches. */
59
+ export declare function frameFileName(index: number): string;
60
+ /** The most `beat()` accepts: longer is almost surely milliseconds passed where seconds are meant. */
61
+ export declare const MAX_BEAT_SECONDS = 60;
62
+ export declare function assertKind(kind: unknown): FilmKind;
63
+ export declare function assertFps(fps: number | undefined, what?: string): number;
64
+ export declare function assertScale(scale: number, what: string): number;
65
+ export declare function assertCaptions(captions: unknown): readonly string[];
66
+ export declare function assertHold(hold: number): number;
67
+ /** The caption index of a shot, or null. An index outside `captions` is a typo in the spec, so it fails. */
68
+ export declare function resolveCaptionIndex(caption: number | undefined, captions: readonly string[]): number | null;
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 declare function addFrame(manifest: FilmManifest, frame: FilmFrame, size: Size): FilmManifest;
74
+ export declare function serializeManifest(manifest: FilmManifest): string;
75
+ /** Reads a manifest written by `serializeManifest`; fails naming the first field that is wrong. */
76
+ export declare function parseFilmManifest(text: string): FilmManifest;