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.
- package/LICENSE +21 -0
- package/README.md +223 -2
- package/bin/opdk.js +34 -0
- package/dist/build/args.d.ts +10 -0
- package/dist/build/args.js +45 -0
- package/dist/build/bundle-check.d.ts +17 -0
- package/dist/build/bundle-check.js +42 -0
- package/dist/build/bundle-file.d.ts +4 -0
- package/dist/build/bundle-file.js +29 -0
- package/dist/build/commands.d.ts +5 -0
- package/dist/build/commands.js +109 -0
- package/dist/build/config.d.ts +3 -0
- package/dist/build/config.js +103 -0
- package/dist/build/css-imports.d.ts +23 -0
- package/dist/build/css-imports.js +50 -0
- package/dist/build/css-step.d.ts +10 -0
- package/dist/build/css-step.js +27 -0
- package/dist/build/css.d.ts +24 -0
- package/dist/build/css.js +47 -0
- package/dist/build/options.d.ts +55 -0
- package/dist/build/options.js +70 -0
- package/dist/build/release.d.ts +5 -0
- package/dist/build/release.js +34 -0
- package/dist/build/report.d.ts +7 -0
- package/dist/build/report.js +16 -0
- package/dist/build/vault.d.ts +26 -0
- package/dist/build/vault.js +290 -0
- package/dist/build-info.json +1 -0
- package/dist/cli/argv.d.ts +14 -0
- package/dist/cli/argv.js +18 -0
- package/dist/cli/commands.d.ts +3 -0
- package/dist/cli/commands.js +7 -0
- package/dist/cli/main.d.ts +2 -0
- package/dist/cli/main.js +23 -0
- package/dist/cli/process-reporter.d.ts +5 -0
- package/dist/cli/process-reporter.js +15 -0
- package/dist/cli/registry.d.ts +4 -0
- package/dist/cli/registry.js +15 -0
- package/dist/cli/reporter.d.ts +53 -0
- package/dist/cli/reporter.js +100 -0
- package/dist/cli/run.d.ts +9 -0
- package/dist/cli/run.js +61 -0
- package/dist/cli/types.d.ts +27 -0
- package/dist/cli/types.js +1 -0
- package/dist/cli/version.d.ts +13 -0
- package/dist/cli/version.js +61 -0
- package/dist/config/define-config.d.ts +3 -0
- package/dist/config/define-config.js +4 -0
- package/dist/config/load-config.d.ts +6 -0
- package/dist/config/load-config.js +70 -0
- package/dist/config/manifest.d.ts +3 -0
- package/dist/config/manifest.js +72 -0
- package/dist/config/types.d.ts +146 -0
- package/dist/config/types.js +23 -0
- package/dist/demo/args.d.ts +4 -0
- package/dist/demo/args.js +13 -0
- package/dist/demo/checks.d.ts +56 -0
- package/dist/demo/checks.js +124 -0
- package/dist/demo/commands.d.ts +3 -0
- package/dist/demo/commands.js +65 -0
- package/dist/demo/config.d.ts +57 -0
- package/dist/demo/config.js +337 -0
- package/dist/demo/ffmpeg-run.d.ts +18 -0
- package/dist/demo/ffmpeg-run.js +59 -0
- package/dist/demo/ffmpeg.d.ts +63 -0
- package/dist/demo/ffmpeg.js +111 -0
- package/dist/demo/films.d.ts +46 -0
- package/dist/demo/films.js +134 -0
- package/dist/demo/phone-layout.d.ts +38 -0
- package/dist/demo/phone-layout.js +98 -0
- package/dist/demo/phone-render.d.ts +28 -0
- package/dist/demo/phone-render.js +124 -0
- package/dist/demo/published.d.ts +16 -0
- package/dist/demo/published.js +72 -0
- package/dist/demo/run.d.ts +31 -0
- package/dist/demo/run.js +397 -0
- package/dist/demo/stills.d.ts +21 -0
- package/dist/demo/stills.js +62 -0
- package/dist/e2e/artifacts.d.ts +27 -0
- package/dist/e2e/artifacts.js +90 -0
- package/dist/e2e/cleanup.d.ts +54 -0
- package/dist/e2e/cleanup.js +109 -0
- package/dist/e2e/config.d.ts +9 -0
- package/dist/e2e/config.js +42 -0
- package/dist/e2e/create-test.d.ts +37 -0
- package/dist/e2e/create-test.js +109 -0
- package/dist/e2e/demo/clip.d.ts +21 -0
- package/dist/e2e/demo/clip.js +44 -0
- package/dist/e2e/demo/create-demo.d.ts +42 -0
- package/dist/e2e/demo/create-demo.js +439 -0
- package/dist/e2e/demo/manifest.d.ts +76 -0
- package/dist/e2e/demo/manifest.js +168 -0
- package/dist/e2e/demo/names.d.ts +18 -0
- package/dist/e2e/demo/names.js +44 -0
- package/dist/e2e/demo/options.d.ts +22 -0
- package/dist/e2e/demo/options.js +59 -0
- package/dist/e2e/demo/ownership.d.ts +27 -0
- package/dist/e2e/demo/ownership.js +65 -0
- package/dist/e2e/demo/page-scripts.d.ts +82 -0
- package/dist/e2e/demo/page-scripts.js +250 -0
- package/dist/e2e/demo/png.d.ts +8 -0
- package/dist/e2e/demo/png.js +23 -0
- package/dist/e2e/demo/presets.d.ts +43 -0
- package/dist/e2e/demo/presets.js +20 -0
- package/dist/e2e/demo/privacy.d.ts +18 -0
- package/dist/e2e/demo/privacy.js +30 -0
- package/dist/e2e/demo/still-options.d.ts +22 -0
- package/dist/e2e/demo/still-options.js +68 -0
- package/dist/e2e/demo/types.d.ts +184 -0
- package/dist/e2e/demo/types.js +1 -0
- package/dist/e2e/electron-binary.d.ts +15 -0
- package/dist/e2e/electron-binary.js +30 -0
- package/dist/e2e/fixtures.d.ts +62 -0
- package/dist/e2e/fixtures.js +68 -0
- package/dist/e2e/gate.d.ts +4 -0
- package/dist/e2e/gate.js +8 -0
- package/dist/e2e/global-setup.d.ts +11 -0
- package/dist/e2e/global-setup.js +17 -0
- package/dist/e2e/helpers/commands.d.ts +14 -0
- package/dist/e2e/helpers/commands.js +56 -0
- package/dist/e2e/helpers/create-helpers.d.ts +24 -0
- package/dist/e2e/helpers/create-helpers.js +582 -0
- package/dist/e2e/helpers/device-metrics.d.ts +21 -0
- package/dist/e2e/helpers/device-metrics.js +25 -0
- package/dist/e2e/helpers/ime.d.ts +13 -0
- package/dist/e2e/helpers/ime.js +19 -0
- package/dist/e2e/helpers/layout-page-scripts.d.ts +103 -0
- package/dist/e2e/helpers/layout-page-scripts.js +224 -0
- package/dist/e2e/helpers/layout.d.ts +83 -0
- package/dist/e2e/helpers/layout.js +148 -0
- package/dist/e2e/helpers/mobile.d.ts +31 -0
- package/dist/e2e/helpers/mobile.js +26 -0
- package/dist/e2e/helpers/page-scripts.d.ts +194 -0
- package/dist/e2e/helpers/page-scripts.js +467 -0
- package/dist/e2e/helpers/settings.d.ts +8 -0
- package/dist/e2e/helpers/settings.js +16 -0
- package/dist/e2e/helpers/settle.d.ts +28 -0
- package/dist/e2e/helpers/settle.js +33 -0
- package/dist/e2e/helpers/types.d.ts +193 -0
- package/dist/e2e/helpers/types.js +1 -0
- package/dist/e2e/helpers/view-mode.d.ts +23 -0
- package/dist/e2e/helpers/view-mode.js +35 -0
- package/dist/e2e/index.d.ts +14 -0
- package/dist/e2e/index.js +4 -0
- package/dist/e2e/internals.d.ts +155 -0
- package/dist/e2e/internals.js +8 -0
- package/dist/e2e/obsidian-path.d.ts +17 -0
- package/dist/e2e/obsidian-path.js +31 -0
- package/dist/e2e/options.d.ts +123 -0
- package/dist/e2e/options.js +244 -0
- package/dist/e2e/page-scripts.d.ts +45 -0
- package/dist/e2e/page-scripts.js +53 -0
- package/dist/e2e/peers.d.ts +9 -0
- package/dist/e2e/peers.js +19 -0
- package/dist/e2e/plugins.d.ts +32 -0
- package/dist/e2e/plugins.js +119 -0
- package/dist/e2e/process-tree.d.ts +33 -0
- package/dist/e2e/process-tree.js +133 -0
- package/dist/e2e/readiness.d.ts +23 -0
- package/dist/e2e/readiness.js +63 -0
- package/dist/e2e/seed.d.ts +34 -0
- package/dist/e2e/seed.js +122 -0
- package/dist/e2e/session.d.ts +71 -0
- package/dist/e2e/session.js +266 -0
- package/dist/e2e/vault.d.ts +52 -0
- package/dist/e2e/vault.js +146 -0
- package/dist/e2e/version.d.ts +25 -0
- package/dist/e2e/version.js +40 -0
- package/dist/eslint/index.d.ts +2 -0
- package/dist/eslint/index.js +1 -0
- package/dist/eslint/obsidian-plugin.d.ts +49 -0
- package/dist/eslint/obsidian-plugin.js +115 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +1 -0
- package/dist/kit/args.d.ts +7 -0
- package/dist/kit/args.js +21 -0
- package/dist/kit/commands.d.ts +3 -0
- package/dist/kit/commands.js +52 -0
- package/dist/kit/files.d.ts +3 -0
- package/dist/kit/files.js +24 -0
- package/dist/kit/pins.d.ts +89 -0
- package/dist/kit/pins.js +178 -0
- package/dist/kit/remote.d.ts +13 -0
- package/dist/kit/remote.js +33 -0
- package/dist/kit/runners.d.ts +11 -0
- package/dist/kit/runners.js +53 -0
- package/dist/kit/terminal-text.d.ts +6 -0
- package/dist/kit/terminal-text.js +20 -0
- package/dist/kit/upgrade.d.ts +26 -0
- package/dist/kit/upgrade.js +162 -0
- package/dist/peers/resolve.d.ts +8 -0
- package/dist/peers/resolve.js +28 -0
- package/dist/peers/versions.d.ts +30 -0
- package/dist/peers/versions.js +32 -0
- package/dist/release/api-check.d.ts +27 -0
- package/dist/release/api-check.js +119 -0
- package/dist/release/args.d.ts +40 -0
- package/dist/release/args.js +120 -0
- package/dist/release/assets.d.ts +21 -0
- package/dist/release/assets.js +35 -0
- package/dist/release/build-check.d.ts +43 -0
- package/dist/release/build-check.js +184 -0
- package/dist/release/build-script.d.ts +12 -0
- package/dist/release/build-script.js +30 -0
- package/dist/release/build-tagged.d.ts +26 -0
- package/dist/release/build-tagged.js +52 -0
- package/dist/release/bump.d.ts +24 -0
- package/dist/release/bump.js +58 -0
- package/dist/release/changelog.d.ts +25 -0
- package/dist/release/changelog.js +148 -0
- package/dist/release/check.d.ts +38 -0
- package/dist/release/check.js +150 -0
- package/dist/release/commands.d.ts +3 -0
- package/dist/release/commands.js +154 -0
- package/dist/release/committed-tree.d.ts +63 -0
- package/dist/release/committed-tree.js +118 -0
- package/dist/release/config.d.ts +3 -0
- package/dist/release/config.js +28 -0
- package/dist/release/gh-access.d.ts +14 -0
- package/dist/release/gh-access.js +45 -0
- package/dist/release/gh.d.ts +10 -0
- package/dist/release/gh.js +33 -0
- package/dist/release/git.d.ts +49 -0
- package/dist/release/git.js +111 -0
- package/dist/release/interrupt.d.ts +30 -0
- package/dist/release/interrupt.js +60 -0
- package/dist/release/json.d.ts +33 -0
- package/dist/release/json.js +81 -0
- package/dist/release/kit-check.d.ts +8 -0
- package/dist/release/kit-check.js +51 -0
- package/dist/release/manifest-rules.d.ts +23 -0
- package/dist/release/manifest-rules.js +255 -0
- package/dist/release/preflight.d.ts +10 -0
- package/dist/release/preflight.js +65 -0
- package/dist/release/problems.d.ts +24 -0
- package/dist/release/problems.js +11 -0
- package/dist/release/project-files.d.ts +14 -0
- package/dist/release/project-files.js +16 -0
- package/dist/release/publish-command.d.ts +21 -0
- package/dist/release/publish-command.js +83 -0
- package/dist/release/publish-git.d.ts +37 -0
- package/dist/release/publish-git.js +108 -0
- package/dist/release/publish-state.d.ts +29 -0
- package/dist/release/publish-state.js +70 -0
- package/dist/release/publish-verify.d.ts +41 -0
- package/dist/release/publish-verify.js +112 -0
- package/dist/release/publish-wait.d.ts +25 -0
- package/dist/release/publish-wait.js +56 -0
- package/dist/release/publish.d.ts +35 -0
- package/dist/release/publish.js +181 -0
- package/dist/release/release-assets.d.ts +39 -0
- package/dist/release/release-assets.js +68 -0
- package/dist/release/release.d.ts +37 -0
- package/dist/release/release.js +179 -0
- package/dist/release/remote.d.ts +12 -0
- package/dist/release/remote.js +15 -0
- package/dist/release/reproducible.d.ts +16 -0
- package/dist/release/reproducible.js +34 -0
- package/dist/release/run-tests.d.ts +5 -0
- package/dist/release/run-tests.js +17 -0
- package/dist/release/semver.d.ts +8 -0
- package/dist/release/semver.js +60 -0
- package/dist/release/version-rules.d.ts +28 -0
- package/dist/release/version-rules.js +63 -0
- package/dist/release/versions-json.d.ts +15 -0
- package/dist/release/versions-json.js +88 -0
- package/dist/release/workflow-run.d.ts +44 -0
- package/dist/release/workflow-run.js +71 -0
- package/dist/scanner/code-checks.d.ts +41 -0
- package/dist/scanner/code-checks.js +82 -0
- package/dist/scanner/commands.d.ts +3 -0
- package/dist/scanner/commands.js +43 -0
- package/dist/scanner/config.d.ts +7 -0
- package/dist/scanner/config.js +25 -0
- package/dist/scanner/css-check.d.ts +26 -0
- package/dist/scanner/css-check.js +63 -0
- package/dist/scanner/eslint-nesting.d.ts +16 -0
- package/dist/scanner/eslint-nesting.js +45 -0
- package/dist/scanner/findings.d.ts +23 -0
- package/dist/scanner/findings.js +21 -0
- package/dist/scanner/git-files.d.ts +16 -0
- package/dist/scanner/git-files.js +73 -0
- package/dist/scanner/lint.d.ts +47 -0
- package/dist/scanner/lint.js +163 -0
- package/dist/scanner/meta-checks.d.ts +8 -0
- package/dist/scanner/meta-checks.js +22 -0
- package/dist/scanner/outside-project.d.ts +19 -0
- package/dist/scanner/outside-project.js +20 -0
- package/dist/scanner/run.d.ts +19 -0
- package/dist/scanner/run.js +78 -0
- package/dist/scanner/scanner-config.d.ts +114 -0
- package/dist/scanner/scanner-config.js +207 -0
- package/dist/scanner/typescript-gate.d.ts +30 -0
- package/dist/scanner/typescript-gate.js +73 -0
- package/dist/vitest/build-config.d.ts +17 -0
- package/dist/vitest/build-config.js +106 -0
- package/dist/vitest/define-unit-config.d.ts +27 -0
- package/dist/vitest/define-unit-config.js +45 -0
- package/dist/vitest/dom/elements.d.ts +87 -0
- package/dist/vitest/dom/elements.js +291 -0
- package/dist/vitest/dom/index.d.ts +1 -0
- package/dist/vitest/dom/index.js +1 -0
- package/dist/vitest/dom/install.d.ts +8 -0
- package/dist/vitest/dom/install.js +261 -0
- package/dist/vitest/dom/setup.d.ts +1 -0
- package/dist/vitest/dom/setup.js +3 -0
- package/dist/vitest/index.d.ts +3 -0
- package/dist/vitest/index.js +2 -0
- package/dist/vitest/options.d.ts +92 -0
- package/dist/vitest/options.js +136 -0
- package/dist/vitest/peers.d.ts +10 -0
- package/dist/vitest/peers.js +51 -0
- package/dist/vitest/workspace-root.d.ts +7 -0
- package/dist/vitest/workspace-root.js +39 -0
- package/docs/build.md +232 -0
- package/docs/ci.md +182 -0
- package/docs/demo.md +364 -0
- package/docs/e2e.md +563 -0
- package/docs/release.md +374 -0
- package/docs/scanner.md +204 -0
- package/docs/unit.md +291 -0
- package/package.json +100 -4
- package/plugins/opdk/skills/audit/SKILL.md +81 -0
- package/plugins/opdk/skills/build/SKILL.md +79 -0
- package/plugins/opdk/skills/demo/SKILL.md +102 -0
- package/plugins/opdk/skills/e2e/SKILL.md +132 -0
- package/plugins/opdk/skills/release/SKILL.md +84 -0
- package/plugins/opdk/skills/scanner/SKILL.md +60 -0
- package/plugins/opdk/skills/unit/SKILL.md +90 -0
package/docs/ci.md
ADDED
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
# Continuous integration
|
|
2
|
+
|
|
3
|
+
`.github/workflows/plugin-ci.yml` is a reusable GitHub Actions workflow that checks an Obsidian plugin on every push and pull request: lint, typecheck, unit tests, the community scanner, the release check and the build, then it uploads the bundle. A plugin calls it from a few lines of its own `ci.yml`. The workflow is for Linux runners (its scripts run with bash). Steps that belong to one plugin stay in that plugin, in a second job.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Three plugins each kept a hand-written `ci.yml` of 45 to 75 lines, and they had drifted: the same steps in a different order, on `ubuntu-latest`, with actions pinned to a major tag. One plugin had a lint script that its CI never ran, and each carried its own version check. The workflow keeps the common part in one place, pinned the way `release.yml` is, with a read-only token.
|
|
8
|
+
|
|
9
|
+
## Quick start
|
|
10
|
+
|
|
11
|
+
Add a workflow that calls the kit's, pinned to a full commit SHA, not to a branch or a tag name:
|
|
12
|
+
|
|
13
|
+
```yaml
|
|
14
|
+
# .github/workflows/ci.yml
|
|
15
|
+
name: ci
|
|
16
|
+
on:
|
|
17
|
+
push:
|
|
18
|
+
branches: [main] # use your default branch name
|
|
19
|
+
pull_request:
|
|
20
|
+
|
|
21
|
+
concurrency:
|
|
22
|
+
group: ci-${{ github.ref }}
|
|
23
|
+
cancel-in-progress: true
|
|
24
|
+
|
|
25
|
+
permissions:
|
|
26
|
+
contents: read
|
|
27
|
+
|
|
28
|
+
jobs:
|
|
29
|
+
kit:
|
|
30
|
+
uses: Dimagious/obsidian-plugin-dev-kit/.github/workflows/plugin-ci.yml@<full commit SHA of the kit>
|
|
31
|
+
|
|
32
|
+
# Optional: whatever only this plugin checks. Runs in parallel with the job above.
|
|
33
|
+
plugin:
|
|
34
|
+
runs-on: ubuntu-24.04
|
|
35
|
+
steps:
|
|
36
|
+
- uses: actions/checkout@<full commit SHA>
|
|
37
|
+
with:
|
|
38
|
+
persist-credentials: false
|
|
39
|
+
- run: node scripts/site-check.cjs
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The plugin needs `obsidian-plugin-dev-kit` as a dev dependency (the workflow runs `node_modules/.bin/opdk`), a `package-lock.json` (it runs `npm ci`) and a `manifest.json` at the root. Concurrency stays in the caller: a reusable workflow cannot cancel the caller's runs.
|
|
43
|
+
|
|
44
|
+
## Inputs
|
|
45
|
+
|
|
46
|
+
All inputs are optional.
|
|
47
|
+
|
|
48
|
+
| Input | Type | Default | Meaning |
|
|
49
|
+
|---|---|---|---|
|
|
50
|
+
| `node-version` | string | `"22"` | Node.js version for every step |
|
|
51
|
+
| `runs-on` | string | `ubuntu-24.04` | Runner label (see "Why ubuntu-24.04") |
|
|
52
|
+
| `lint` | boolean | `true` | `npm run lint`. Skipped with a notice when `package.json` has no `lint` script |
|
|
53
|
+
| `typecheck` | boolean | `true` | `npm run typecheck`, or `node_modules/.bin/tsc --noEmit` when there is no such script. Fails when neither exists |
|
|
54
|
+
| `test` | boolean | `true` | `npm run test` |
|
|
55
|
+
| `scan` | boolean | `true` | `node_modules/.bin/opdk scan` |
|
|
56
|
+
| `release-check` | boolean | `true` | `node_modules/.bin/opdk release check --no-build --no-api` |
|
|
57
|
+
| `build` | boolean | `true` | `npm run build` |
|
|
58
|
+
| `upload-bundle` | boolean | `true` | Upload `main.js`, `manifest.json` and `styles.css` (when it exists) as the artifact `<plugin id>-bundle`. A missing or empty `main.js` or `manifest.json` fails the job |
|
|
59
|
+
| `coverage-artifact` | boolean | `false` | Upload `coverage/**` as the artifact `<plugin id>-coverage`. Fails when the folder is empty or missing |
|
|
60
|
+
|
|
61
|
+
No input takes a command. A caller cannot make the workflow run a string it passed in; a different command for a step is the plugin's own script (`npm run lint` runs whatever `scripts.lint` says), or a step in the plugin's second job. `upload-bundle` needs the `build` step in this job: `build: false` with `upload-bundle: true` fails unless the repository commits its `main.js`.
|
|
62
|
+
|
|
63
|
+
## What each step runs
|
|
64
|
+
|
|
65
|
+
Every step is one command. The job stops at the first failure.
|
|
66
|
+
|
|
67
|
+
1. `actions/checkout` with `persist-credentials: false`, then `actions/setup-node` with the npm cache.
|
|
68
|
+
2. Read the plugin id from `manifest.json` (the artifact names use it; an id that is not safe in a file name stops the job).
|
|
69
|
+
3. `npm ci`.
|
|
70
|
+
4. Lint, typecheck, unit tests (the three switches above).
|
|
71
|
+
5. `opdk scan`: the community scanner's checks, see [scanner.md](scanner.md).
|
|
72
|
+
6. `opdk release check --no-build --no-api`: versions in `package.json`, `manifest.json`, `package-lock.json` and `versions.json`, the manifest rules, a CHANGELOG section for the current version, and the `kit` pins (see [Updating the kit](#updating-the-kit)). The build, reproducibility and API checks are left out: the build step builds once, and the full check runs on the tag in `release.yml`. See [release.md](release.md).
|
|
73
|
+
7. `npm run build`.
|
|
74
|
+
8. The bundle check and the artifact uploads.
|
|
75
|
+
|
|
76
|
+
The plugin's `build` script should run `opdk build`, as the release module requires.
|
|
77
|
+
|
|
78
|
+
## Permissions
|
|
79
|
+
|
|
80
|
+
The workflow sets `permissions: {}` at the top and gives its one job `contents: read`. No step can push, create a release or sign. The caller has to grant at least `contents: read` (a called workflow cannot ask for more than its caller allows). Every action is pinned to a full commit SHA with the version in a comment. No `${{ }}` expression appears inside a `run:` script, and no caller value reaches a script: the plugin id is read from `manifest.json` inside the step. A test in the kit (`src/ci/plugin-ci-workflow.test.ts`) fails when one of these breaks, including a pinned action that lost its version comment.
|
|
81
|
+
|
|
82
|
+
The npm cache is on in this workflow. Any job can write the Actions cache whatever its `permissions` say, so the read-only token is not the reason. The reasons are that nothing this job builds is shipped, and that npm checks cached tarballs against the hashes in `package-lock.json`. `release.yml`, whose build is attested and shipped, restores no cache. For the same reason, do not enable the npm cache in your own release or other privileged workflows.
|
|
83
|
+
|
|
84
|
+
## Updating the kit
|
|
85
|
+
|
|
86
|
+
A plugin pins the kit in three places that have to name one release: the tag in `package.json` (`github:Dimagious/obsidian-plugin-dev-kit#vX.Y.Z`), the commit the lockfile resolved it to, and the commit in every `uses: Dimagious/obsidian-plugin-dev-kit/.github/workflows/<file>@<sha> # vX.Y.Z` line of `.github/workflows/`. Moving one and forgetting another leaves CI running one kit version and the release workflow another, and nothing in either run says so.
|
|
87
|
+
|
|
88
|
+
- **Learn about a release.** Watch the kit's repository on GitHub (Watch, Custom, Releases). Configure Dependabot to ignore the kit. It would bump the `uses:` pins and the dependency in separate pull requests, and a bump of one pin alone makes `opdk release check` fail (and would let the release workflow run a kit version that does not match the `opdk` in `node_modules`). Add one `ignore` entry to each ecosystem in `.github/dependabot.yml`; use your kit's owner in place of `<owner>` (`Dimagious` for the upstream kit):
|
|
89
|
+
|
|
90
|
+
```yaml
|
|
91
|
+
version: 2
|
|
92
|
+
updates:
|
|
93
|
+
- package-ecosystem: npm
|
|
94
|
+
directory: /
|
|
95
|
+
schedule:
|
|
96
|
+
interval: weekly
|
|
97
|
+
ignore:
|
|
98
|
+
- dependency-name: "obsidian-plugin-dev-kit"
|
|
99
|
+
- package-ecosystem: github-actions
|
|
100
|
+
directory: /
|
|
101
|
+
schedule:
|
|
102
|
+
interval: weekly
|
|
103
|
+
ignore:
|
|
104
|
+
- dependency-name: "<owner>/obsidian-plugin-dev-kit*"
|
|
105
|
+
```
|
|
106
|
+
- **Move to it.** From a clean tree on a branch:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
npx opdk kit upgrade --dry-run # the lines that would change, and what the kit changed
|
|
110
|
+
npx opdk kit upgrade # latest release; or: npx opdk kit upgrade v0.3.2
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
A plugin on v0.1.0 has no `kit` command yet, so `npx opdk kit upgrade` stops with `unknown command "kit"`. Run the new release's `opdk` once through npx instead; npx builds the kit in its own cache, which took about a minute on each of three plugins:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
npx -y -p github:Dimagious/obsidian-plugin-dev-kit#v0.3.2 opdk kit upgrade v0.3.2
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
From v0.2.0 on, the installed `opdk` has the command.
|
|
120
|
+
|
|
121
|
+
The command finds the latest `vX.Y.Z` tag with `git ls-remote --tags` on the kit's repository (no GitHub login), resolves the tag to its commit, rewrites the tag in `package.json`, runs `npm install` for that one package so the lockfile follows (npm builds the kit, which takes a minute), rewrites every kit `uses:` line to the new commit with a `# vX.Y.Z` comment, and then runs the `kit` step of `opdk release check`. If `npm install` fails, `package.json` and the lockfile are put back and no workflow file is touched; npm may have left `node_modules` half installed, so run `npm ci` if it looks off. Only `uses:` lines of the owner named in `package.json` are rewritten. Without a lockfile npm does not run, the command says so, and `node_modules` keeps the old kit until you run `npm install`. `git ls-remote` is stopped after 60 seconds and `npm install` after 10 minutes. Before it writes anything it prints the kit's CHANGELOG sections between your version and the new one, read from the tag on GitHub (when GitHub cannot be reached it says so and goes on).
|
|
122
|
+
- **Review and ship.** The command never commits or pushes. Look at `git diff`, read the changelog it printed, commit on a branch, open a pull request and let CI run: it is the first run with the new kit.
|
|
123
|
+
- **The check.** `opdk release check`, and so the CI workflow's `release-check` step, fails when the places disagree. It needs no network: the lockfile's `version` stands for the tag. The failure names each place with the commit it holds and points at `opdk kit upgrade`; running the command again, with the tag you meant, repairs a plugin that drifted.
|
|
124
|
+
|
|
125
|
+
```text
|
|
126
|
+
✗ check kit: the kit is not pinned to one release.
|
|
127
|
+
the places below name 2 different commits of the kit.
|
|
128
|
+
package.json asks for v0.2.0, but the lockfile holds kit version 0.1.0.
|
|
129
|
+
package.json (devDependencies): v0.2.0
|
|
130
|
+
package-lock.json: commit 6e33ca4, version 0.1.0
|
|
131
|
+
.github/workflows/ci.yml:18: commit a1b2c3d (# v0.2.0)
|
|
132
|
+
Run `opdk kit upgrade v0.2.0` to rewrite the lockfile and the workflow pins to one commit (`opdk kit upgrade` alone takes the latest release), then commit the result.
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
A plugin that does not call the kit's workflows has only `package.json` and the lockfile to compare, and a plugin that does not depend on the kit passes.
|
|
136
|
+
|
|
137
|
+
## Why ubuntu-24.04
|
|
138
|
+
|
|
139
|
+
On 2026-11-11 the `ubuntu-latest` image (26.04) could not resolve the Ubuntu archive, and a CI job in the kit hung on `apt-get` until it timed out. Move to the next LTS on purpose, by passing `runs-on`, not by an alias that changes under you. The plugin's second job should pin the same label. The reusable `release.yml` takes the same `runs-on` input, with the same default.
|
|
140
|
+
|
|
141
|
+
## Keeping plugin-specific steps
|
|
142
|
+
|
|
143
|
+
Put them in a second job of the caller. The two jobs run in parallel; add `needs: kit` to a job that should wait. Examples that stay in plugins: checks that generated files are in sync (`build:skill -- --check`), a project site check (`site:check`), a README check (`readme:check`) and a Codecov upload.
|
|
144
|
+
|
|
145
|
+
For coverage services, ask for the report and download it in the second job:
|
|
146
|
+
|
|
147
|
+
```yaml
|
|
148
|
+
jobs:
|
|
149
|
+
kit:
|
|
150
|
+
uses: Dimagious/obsidian-plugin-dev-kit/.github/workflows/plugin-ci.yml@<full commit SHA of the kit>
|
|
151
|
+
with:
|
|
152
|
+
coverage-artifact: true
|
|
153
|
+
coverage:
|
|
154
|
+
needs: kit
|
|
155
|
+
runs-on: ubuntu-24.04
|
|
156
|
+
steps:
|
|
157
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
158
|
+
with:
|
|
159
|
+
persist-credentials: false
|
|
160
|
+
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
|
|
161
|
+
with:
|
|
162
|
+
name: <plugin id>-coverage
|
|
163
|
+
- uses: codecov/codecov-action@<full commit SHA> # v<version>
|
|
164
|
+
with:
|
|
165
|
+
files: ./lcov.info
|
|
166
|
+
fail_ci_if_error: true
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
## Migrating a plugin
|
|
170
|
+
|
|
171
|
+
Compare your current `ci.yml` with the workflow, step by step:
|
|
172
|
+
|
|
173
|
+
- **Replaced by the workflow.** Install, lint, typecheck, a version check (`assert-versions`-style scripts), a scorecard gate (`opdk scan`), unit tests, the build and the bundle upload. Delete them from your `ci.yml` and call the workflow.
|
|
174
|
+
- **Stays in your own job.** Steps that belong to one plugin: generated files in sync, a project site build, README checks, a coverage service upload (needs `coverage-artifact: true`, see above).
|
|
175
|
+
- **A zip is no longer built or uploaded.** If your CI ran a `release:zip` script and uploaded `<plugin>-*.zip`, drop both; the release workflow makes a zip only on request.
|
|
176
|
+
- **The release check is stricter than a hand-written version script.** It also wants a CHANGELOG section, the manifest rules and the versions in `package-lock.json`, and it needs a `versions.json` (see the release docs).
|
|
177
|
+
- **A lint script your CI never ran now runs.** Fix its findings, or pass `lint: false` until you do.
|
|
178
|
+
- **No `typecheck` script.** The workflow runs `tsc --noEmit` (the same as `npx tsc -p tsconfig.json --noEmit` while the tsconfig is the default one).
|
|
179
|
+
- **A default branch that is not `main`.** Use its name in `branches` in the caller.
|
|
180
|
+
- **The separate coverage artifact** is named `<plugin id>-coverage`.
|
|
181
|
+
|
|
182
|
+
The runner moves from `ubuntu-latest` to `ubuntu-24.04`; actions move from major tags to pinned SHAs; the bundle artifact keeps the name `<id>-bundle`. The plugin's `release:check` and `release:zip` npm scripts are not used by this workflow.
|
package/docs/demo.md
ADDED
|
@@ -0,0 +1,364 @@
|
|
|
1
|
+
# Demo films
|
|
2
|
+
|
|
3
|
+
The `demo` fixture of `obsidian-plugin-dev-kit/e2e` records your plugin in the real Obsidian as a film of stills: a spec says "this frame, held for this many seconds, with this caption", and the kit takes a sharp, frozen picture of the window for each. `opdk demo` then turns the film into an MP4, a GIF and a poster, and, for a phone film with `layout: "phone-captions"` set in `opdk.config.mjs`, puts each frame beside its list of captions. No audio, no intro or outro cards.
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
The film above is the kit's own: `test/e2e-fixture/e2e/docs-film.spec.ts` records it on the kit's fixture plugin and seed vault, and `npm run docs:media:demo` encodes it with the settings in the kit's `opdk.config.mjs`.
|
|
8
|
+
|
|
9
|
+
## Why
|
|
10
|
+
|
|
11
|
+
Hand-written demo scripts have cost real plugins these things:
|
|
12
|
+
|
|
13
|
+
- Recording the Obsidian window as video caught every stutter of the machine and the cursor wherever it was, and that plugin's build script needed `python3` to do the rest.
|
|
14
|
+
- A retake appended frames to the old ones instead of replacing them.
|
|
15
|
+
- A reel script only warned when ffmpeg failed, so a run that made no GIF still ended green. Its films were twice as sharp only because the machine is a Retina Mac. A drawn phone film also showed a navigation bar that was wrong for the app; the kit frames the real Obsidian window instead of drawing a phone.
|
|
16
|
+
|
|
17
|
+
A film of stills makes timing a property of the script (`hold`) and not of the machine, pictures are taken at a fixed density (2x by default, on any monitor), a retake replaces the frames, and every encode step that fails fails the film.
|
|
18
|
+
|
|
19
|
+
## What a spec gets
|
|
20
|
+
|
|
21
|
+
`createObsidianTest` returns a `demo` fixture next to `win`, `app`, `vault` and `obsidian`:
|
|
22
|
+
|
|
23
|
+
| Part | What it does |
|
|
24
|
+
|---|---|
|
|
25
|
+
| `demo.film(options)` | Starts a film of stills. Returns a `Film` with `name`, `dir` and `shot({ hold, caption?, clip?, padding?, settle? })` |
|
|
26
|
+
| `demo.still(name, options?)` | One PNG, `<outDir>/stills/<name>.png`, optionally at the exact pixels of a destination (`preset`). `opdk demo` publishes it, to the default folder, to a folder of its own (`out`) or not at all (`publish: false`) |
|
|
27
|
+
| `demo.moveAndClick(target)`, `demo.tap(target, { whilePressed? })` | A visible cursor that travels to the target and clicks it (desktop), or a tap dot that presses and releases (phone) |
|
|
28
|
+
| `demo.typeSlowly(text)`, `demo.typeSlowly(target, text)` | Types key by key, 40 ms apart by default |
|
|
29
|
+
| `demo.caption(text \| null)` | A caption bar at the bottom of the window, drawn into every frame until changed |
|
|
30
|
+
| `demo.beat(seconds)`, `demo.hideCursor()` | A deliberate pause for pacing a Playwright video of a test (the kit films stills only), and hiding the cursor or tap dot |
|
|
31
|
+
| `demo.cleanUi(options?)` | Hides the ribbon, status bar, tab headers, view header and inline title, and folds both sidebars |
|
|
32
|
+
| `demo.freezeTime(date)` | Fixes the window's clock |
|
|
33
|
+
| `demo.themes(["light", "dark"], scene)` | Runs a scene once per theme and names the output `-light` and `-dark` |
|
|
34
|
+
|
|
35
|
+
Every shot first freezes the page (after `obsidian.settle()` when the shot passes `settle: true`, see **Settling**): CSS transitions end, running animations finish (endless ones are paused for the picture and played again), the caret and the CodeMirror cursor layer are hidden, and two animation frames are awaited. Then the picture is taken through the same CDP session as the `obsidian` helpers, so it keeps the mobile emulation.
|
|
36
|
+
|
|
37
|
+
A plain `win.screenshot()` in the same test is fine, but the picture it takes is at the display's density (1x on a 1x display), not the fixture's. Playwright's screenshot drops the device metrics override from the page. The next `film.shot()` or `demo.still()` restores size and scale, on the desktop and after `obsidian.mobile()` alike: a phone film comes back at the phone size the session last set, at the film's scale (live tests: `a plain win.screenshot() between demo shots does not change the density of the next one` and `... after obsidian.mobile() leaves the next phone shot ...`). A second `obsidian.mobile()` after a plain screenshot restores the phone size as well. Use `demo.still()` for pictures that are published.
|
|
38
|
+
|
|
39
|
+
## Quick start
|
|
40
|
+
|
|
41
|
+
1. Install `ffmpeg`. `opdk demo` uses `OPDK_FFMPEG` when set (no fallback), otherwise `PATH`. macOS: `brew install ffmpeg`; Debian or Ubuntu: `sudo apt install ffmpeg`; Windows: `winget install ffmpeg`. The MP4 needs the `libx264` encoder, which the common builds have.
|
|
42
|
+
2. Set up the e2e module first ([docs/e2e.md](e2e.md)): `@playwright/test`, `electron` and the kit as devDependencies, a seed vault and `createObsidianTest`. The `phone-captions` layout renders in Electron from the same `electron` devDependency, so it needs nothing extra. A plain layout needs neither Electron nor Playwright when `opdk demo` runs.
|
|
43
|
+
3. Add `.opdk/` to `.gitignore`. The default output folder of the fixture, `.opdk/demo`, holds raw frames of the app and is not meant to be committed.
|
|
44
|
+
4. Use the `demo` option of `createObsidianTest`. It is optional; every key has a default:
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
import { createObsidianTest } from "obsidian-plugin-dev-kit/e2e";
|
|
48
|
+
|
|
49
|
+
export const { test, expect, onlyWhen } = createObsidianTest({
|
|
50
|
+
seedVault: "e2e/vault",
|
|
51
|
+
window: { width: 1200, height: 800 },
|
|
52
|
+
demo: { forbiddenSelectors: [".my-plugin-api-key"] },
|
|
53
|
+
});
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
5. Write a spec that only runs on request, so a normal `playwright test` does not record films:
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
import { expect, onlyWhen, test } from "./fixtures.js";
|
|
60
|
+
|
|
61
|
+
onlyWhen("OPDK_E2E_FILM");
|
|
62
|
+
|
|
63
|
+
test("tour: open a note, type, run a command", async ({ obsidian, demo, win }) => {
|
|
64
|
+
await demo.freezeTime("2026-03-14T09:26:00");
|
|
65
|
+
await obsidian.mobile();
|
|
66
|
+
await obsidian.openFile("Welcome.md", { mode: "source" });
|
|
67
|
+
await demo.cleanUi();
|
|
68
|
+
await obsidian.clearNotices();
|
|
69
|
+
|
|
70
|
+
const film = demo.film({
|
|
71
|
+
name: "tour",
|
|
72
|
+
kind: "phone",
|
|
73
|
+
captions: ["Open a note", "Type\nKey by key", "Run a command"],
|
|
74
|
+
});
|
|
75
|
+
await film.shot({ hold: 1.8, caption: 0 });
|
|
76
|
+
|
|
77
|
+
const editor = win.locator(".cm-content[contenteditable=true]").first();
|
|
78
|
+
await demo.tap(editor);
|
|
79
|
+
await demo.typeSlowly("# Typed by the kit", { delayMs: 40 });
|
|
80
|
+
await expect(editor).toContainText("Typed by the kit");
|
|
81
|
+
await film.shot({ hold: 1.6, caption: 1 });
|
|
82
|
+
|
|
83
|
+
await obsidian.runCommand("my-plugin:insert-date");
|
|
84
|
+
await film.shot({ hold: 1.6, caption: 2 });
|
|
85
|
+
});
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
6. Add the `demo` section to `opdk.config.mjs` (all keys optional, see [Configuration](#configuration)):
|
|
89
|
+
|
|
90
|
+
```js
|
|
91
|
+
import { defineConfig } from "obsidian-plugin-dev-kit";
|
|
92
|
+
|
|
93
|
+
export default defineConfig({
|
|
94
|
+
demo: {
|
|
95
|
+
output: "docs/screens",
|
|
96
|
+
gif: { width: 900 },
|
|
97
|
+
layout: "phone-captions",
|
|
98
|
+
phone: {
|
|
99
|
+
title: "My plugin",
|
|
100
|
+
accent: "#6f4fe0",
|
|
101
|
+
},
|
|
102
|
+
films: {
|
|
103
|
+
overview: { layout: "plain", gif: { colors: 256, fps: 12 }, budget: { warnBytes: 3_000_000 } },
|
|
104
|
+
},
|
|
105
|
+
},
|
|
106
|
+
});
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
7. Add the scripts and run them:
|
|
110
|
+
|
|
111
|
+
```json
|
|
112
|
+
{
|
|
113
|
+
"scripts": {
|
|
114
|
+
"demo:record": "OPDK_E2E_FILM=1 playwright test film",
|
|
115
|
+
"demo": "npm run build && npm run demo:record && opdk demo"
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
The examples above were typechecked against the kit in a temporary project (strict; callbacks that read `document` need "DOM" in `lib`).
|
|
121
|
+
|
|
122
|
+
A film is encoded only when its recording test passed. A test that failed, timed out or was skipped leaves the film marked incomplete. `opdk demo` does not encode it: when you name it on the command line it fails with exit 1 (`<name>: not encoded` and the reason), and incomplete ones print as `!` lines (`<name>: skipped, <reason>`). Without names, when films were recorded and none of them is complete, the exit is 1 (`no complete film among the N recorded`), also when stills exist: stills do not stand in for films. With names, only what was named counts. A project with stills and no film folders at all exits 0.
|
|
123
|
+
|
|
124
|
+
## Recording a film
|
|
125
|
+
|
|
126
|
+
`demo.film({ kind, name?, fps?, captions?, clip?, padding?, scale?, cursor?, forbiddenSelectors?, allowForeignVault? })` starts a film and empties its folder, `<outDir>/films/<name>/`, so a retake replaces the frames of the earlier run.
|
|
127
|
+
|
|
128
|
+
- `kind` is `"phone"` for a film shot in the mobile emulation (`obsidian.mobile()`) and `"desktop"` for one without it. A shot fails when the window is in the other state.
|
|
129
|
+
- `name` defaults to the describe titles and the test title (and the project name when the config has several projects), lower case with dashes. Two tests of one run that get the same name fail with the other test's title, and so do two stills of one name. A later run is a retake and replaces them.
|
|
130
|
+
- `fps` is the rate the MP4 is encoded at, 1 to 60, default 15.
|
|
131
|
+
- `scale` is device pixels per CSS pixel, a whole number from 1 to 4. The default is `demo.scale` of the fixture options, 2.
|
|
132
|
+
- `cursor` is `true` by default; `false` keeps the cursor arrow out of this film's frames (see below).
|
|
133
|
+
|
|
134
|
+
`film.shot({ hold, caption?, clip?, padding?, settle? })` takes one frame. Call it after the assertion that the app is in the state the frame should show: nothing in a shot waits for the app unless it passes `settle: true`.
|
|
135
|
+
|
|
136
|
+
**Holds.** `hold` is seconds on screen and must be above 0. A film of stills takes its timing from `hold` and from nothing else. By default the GIF runs at 10 fps at most (`gif.fps` changes it), so a hold shorter than one GIF frame (0.1 s) can be skipped by the GIF; `opdk demo` warns and names the frame. For typing, take a shot every few characters with a hold of 0.4 to 0.6 s and a longer one at the end, as the film above does.
|
|
137
|
+
|
|
138
|
+
**Settling.** `settle: true` in `film.shot()` or `demo.still()` runs `obsidian.settle()` first: the shot waits until the DOM has been quiet for 150 ms, no font is loading and the images in view are complete, and only then freezes the page. With a `preset` the wait comes after the window has been resized, so the reflow is waited for too. Use it where a spec used to sleep before a picture. The default is `false`: a frame of a loading state that you film on purpose is taken as it is. If the page does not settle within `timeouts.helpers.ui` the shot fails with the error of `settle()` (what kept changing, how to raise the budget) and writes nothing. `settle()` takes `quietMs` and `root` when called on its own ([docs/e2e.md](e2e.md)); the shot options use the defaults, so call `obsidian.settle({ root })` yourself before a shot of a page that has a part that never stops changing. `settle` does not see drawing on a `<canvas>` (a chart) either, so a still of a canvas needs its own wait before the shot: poll a pixel with `getImageData` until it is not blank, or wait for the chart library's ready flag or animation-complete callback. `settle` sees changes that are happening, not ones that are scheduled: a pause longer than `quietMs` before the render looks settled, so assert on the element or raise `quietMs`.
|
|
139
|
+
|
|
140
|
+
**Pacing.** Two to four seconds per step reads well; one second per step is too fast to read a caption. Hold the first and the last frame a little longer than the rest.
|
|
141
|
+
|
|
142
|
+
**Loops.** A GIF repeats, so the film should end on the state it began with. The loop check compares the first and last frame (see Checks). The usual causes of a warning are a caption bar or the cursor arrow that is in the last frame and not in the first: clear them before the last shot (`demo.caption(null)`, `demo.hideCursor()`, or `cursor: false` for the film) so the last frame matches the first. A tour that goes through several screens does not return to the start on purpose; set `loop: "off"` for it in `demo.films.<name>`.
|
|
143
|
+
|
|
144
|
+
**Captions.** There are two kinds, and they are different things:
|
|
145
|
+
|
|
146
|
+
- `captions: [...]` in `film()` is the list that the `phone-captions` layout draws beside the phone. A shot points at one by index (`caption: 1`); a frame without `caption` keeps the previous step in the layout. A caption with a line break (`"Tap a day\nSee its value"`) is drawn as a heading and a text. An index outside the list fails the shot. The texts are not drawn into the frames.
|
|
147
|
+
- `demo.caption("text")` shows a bar at the bottom of the window, in every frame until you change it, and `demo.caption(null)` removes it. The text is plain text. Use it for a desktop film or a plain layout. Keep it under about 60 characters.
|
|
148
|
+
|
|
149
|
+
**Tap or click.** On a phone use `demo.tap(target)`: a small dot appears on the target, presses (it shrinks while the finger is down) and goes away after the finger is up. `tap(target, { whilePressed: () => film.shot({ hold: 0.3 }) })` takes a frame of the press. On the desktop use `demo.moveAndClick(target)`: the cursor travels in 14 steps and clicks. Both fail when the target is not visible. `typeSlowly(target, text)` clicks the target with the cursor first, so on a phone focus the field with `tap` and call `typeSlowly(text)`, which fails when nothing editable has focus. `hideCursor()` hides the cursor or the dot until the mouse moves again, for a frame that should show none.
|
|
150
|
+
|
|
151
|
+
**The cursor follows every mouse action.** The arrow is drawn wherever Playwright's mouse is, so a plain `click()`, `check()`, `selectOption()` or `hover()` moves it too, not only `moveAndClick()`. A film that never meant to show a cursor then has an arrow at the place of the last click. Pass `cursor: false` to `demo.film()` and the arrow stays hidden in that film's frames, however the page was clicked. The setting belongs to the film: a later film or still of the same test without it shows the arrow again. The tap dot of a phone film is not affected. `demo.still(name, { cursor: false })` does the same for one still and, like the film's setting, does not carry over to the next picture (the workaround `demo.hideCursor()` also works, until the mouse moves again).
|
|
152
|
+
|
|
153
|
+
**Pauses in a recorded take.** `demo.beat(seconds)` is a deliberate pause for the viewer of a recording. It is for pacing a Playwright video of a test; the kit films stills only, so use `hold`. It takes seconds (a helper that took milliseconds needs its calls converted) and throws above 60. The helpers do not pause by themselves.
|
|
154
|
+
|
|
155
|
+
**A clean UI.** `demo.cleanUi()` hides the ribbon, the view header and the inline title through Obsidian's own settings (saved at once, because `reload()` reloads without saving) and the status bar and tab headers through a class on the page. It also folds the left and right sidebars (`obsidian.collapseSidebars()`, waiting until they are folded): a frame with the file explorer open loses a fifth of its width to it. `cleanUi({ sidebars: false })` leaves the sidebars as they are. It survives `reload()`, `mobile()` and `desktop()`. Each call sets the five hidden parts, so `cleanUi({ statusBar: false })` hides the other four and shows the status bar, and the last call decides. Nothing is put back afterwards: the window is closed with the test. The sidebars are folded once and not unfolded by a later call. Overlays, the hidden parts and the frozen time all survive a reload, and a film goes on across it.
|
|
156
|
+
|
|
157
|
+
**Frozen time.** `demo.freezeTime(date)` fixes `new Date()`, `Date.now()` and `moment()` of the window at `date`; timers keep running. A date string without a time zone is read in the time zone of the machine and shown in it, so the same test gives the same text everywhere; a string with `Z` or an offset shows a different wall clock time in another zone. Caveats: the dates of files in Obsidian's explorer and in search come from the file system and are not frozen, and code that measures elapsed time with `Date.now()` sees none pass.
|
|
158
|
+
|
|
159
|
+
**Themes.** `demo.themes(["light", "dark"], scene)` runs `scene` once per theme, in order. Inside it `film()` and `still()` add `-light` or `-dark` to their names, so one scene gives `overview-light` and `overview-dark`. The theme stays on the last one afterwards. Settings for a theme pair are read from the base name (`films.overview`), and an exact name (`films["overview-dark"]`) wins over it.
|
|
160
|
+
|
|
161
|
+
**Clip.** `clip` is an element (its bounding box) or a rectangle `{ x, y, width, height }` in CSS pixels from the window's top-left corner, and `padding` adds CSS pixels around it, cut at the window edge. A clip that runs past the window fails instead of being cut: scroll the target into view or make the window bigger. A film's frames all have the same size, so a film-wide clip is set in `film()` and a per-shot one has to give the same size.
|
|
162
|
+
|
|
163
|
+
### Stills
|
|
164
|
+
|
|
165
|
+
`demo.still(name, { preset?, clip?, padding?, scale?, settle?, cursor?, publish?, out? })` writes `<outDir>/stills/<name>.png`, replacing an earlier one. A preset gives exactly its pixels, puts the window at the CSS size that produces them and puts it back afterwards. A preset cannot be combined with `clip` or `scale`.
|
|
166
|
+
|
|
167
|
+
| Preset | Pixels | For |
|
|
168
|
+
|---|---|---|
|
|
169
|
+
| `readme` | 1000 x 640 | a README picture, as wide as GitHub shows it |
|
|
170
|
+
| `listing-desktop` | 1200 x 800 | the community plugin listing, desktop |
|
|
171
|
+
| `listing-phone` | 900 x 1600 | the listing, phone (a 450 x 800 window at 2x) |
|
|
172
|
+
| `social` | 1200 x 630 | a link preview card |
|
|
173
|
+
|
|
174
|
+
`opdk demo` publishes every still: it copies `<outDir>/stills/<name>.png` to the output folder (`docs/screens` by default) as `<name>.png`, next to the films, and only when the bytes there differ, so a retake of an unchanged picture leaves the file and git alone. A still is as sharp as the fixture's density, not the display's, which is the reason to use it for README and listing pictures instead of `win.screenshot()`. `demo.stills: false` turns this off, `demo.stills: { output: "docs/pictures" }` publishes them to another folder. Names on the command line select stills as well as films ([What `opdk demo` does](#what-opdk-demo-does)). Stills are copied as they are: they go through no size budget and no check.
|
|
175
|
+
|
|
176
|
+
**A still that feeds another tool, or goes to its own folder.** Two options say where `opdk demo` puts a still. Both are recorded in `<outDir>/.owners/still-options/<name>.json`, not next to the PNG (a tool that reads `<outDir>/stills` sees only pictures), so a retake with other options replaces what the earlier take asked for, and a still recorded without them behaves as before.
|
|
177
|
+
|
|
178
|
+
- `publish: false` keeps the PNG in `<outDir>/stills` and does not copy it. Use it for a picture that only another tool reads, for example the screens a plugin's own listing composer lays out into store pictures, or the shots of a UI tour that a person looks through next to `obsidian.checkLayout()` ([docs/e2e.md](e2e.md)). The tool or the person reads `<outDir>/stills/<name>.png`.
|
|
179
|
+
- `out: "listing"` copies the still to the folder that `demo.outputs.listing` names in `opdk.config.mjs`, instead of the default one. Use it for pictures that belong in their own place, such as the screenshots a plugin directory lists.
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
await demo.still("settings", { preset: "listing-desktop", out: "listing" }); // docs/listing/settings.png
|
|
183
|
+
await demo.still("phone-key", { preset: "listing-phone", publish: false }); // stays in .opdk/demo/stills for the composer
|
|
184
|
+
await demo.still("hero", { preset: "readme" }); // docs/screens/hero.png, as before
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
```js
|
|
188
|
+
export default defineConfig({
|
|
189
|
+
demo: {
|
|
190
|
+
outputs: { listing: "docs/listing" }, // folder names are one path segment; folders are relative to the plugin root
|
|
191
|
+
},
|
|
192
|
+
});
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
`out` and `publish: false` together fail, because a still that is not copied has no folder. A still that names a folder missing from `demo.outputs` fails the run for that still and says which folders exist; the other stills are still copied. Everything else holds in the named folder as in the default one: copied only when the bytes differ, a film's file is never overwritten, the file is recorded for the stale-media check. A still that used to be published and now has `publish: false` leaves its old copy in place; the stale-media warning names it. `demo.stills: false` turns every still's publishing off, `out` included.
|
|
196
|
+
|
|
197
|
+
### Pixels
|
|
198
|
+
|
|
199
|
+
Frames are taken at `demo.scale` (2 by default), so they are 2x on a 1x monitor too, and every frame is checked against the CSS size of the window times the scale. A 1200 x 800 desktop window gives 2400 x 1600 frames; a phone film in the default emulation (390 x 844 at scale 2) gives 780 x 1688. `opdk demo` warns about a film shot below scale 2 and about a manifest whose size does not match its scale. The GIF is made smaller (up to 1000 px wide by default); the MP4 and the poster keep the frame size.
|
|
200
|
+
|
|
201
|
+
## The privacy guard
|
|
202
|
+
|
|
203
|
+
A picture or film of someone's real notes can be published by mistake. The fixture refuses to capture in two cases:
|
|
204
|
+
|
|
205
|
+
- `OPDK_E2E_VAULT` is set (whatever it points at), which replaces the vault in `createObsidianTest({ seedVault })`:
|
|
206
|
+
|
|
207
|
+
```text
|
|
208
|
+
film "tour" refused: OPDK_E2E_VAULT points this run at /somewhere/real-vault, not at the plugin's own seed vault, and a picture or film of someone's real notes could be published by mistake. Unset OPDK_E2E_VAULT, or pass allowForeignVault: true if you mean to shoot that vault.
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
- The seed vault lies outside the plugin folder, the directory `playwright test` runs in:
|
|
212
|
+
|
|
213
|
+
```text
|
|
214
|
+
film "tour" refused: the seed vault <path> lies outside the plugin folder <path>, and a picture or film of a vault that is not the plugin's own could show private notes. Move the seed vault into the plugin folder, or pass allowForeignVault: true if you mean to shoot that vault.
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
`allowForeignVault: true` in `film()` or `still()` turns the refusal off for that call. Use it only for a vault you made for the purpose.
|
|
218
|
+
|
|
219
|
+
`forbiddenSelectors` are the second guard: CSS selectors that must never be in a picture, for example the element that shows an API key or a real account name. Set them in the `demo` option (`demo.forbiddenSelectors`, for every picture) or in one call (`forbiddenSelectors`). A shot fails when an element that matches one is visible, before anything is written:
|
|
220
|
+
|
|
221
|
+
```text
|
|
222
|
+
film "tour", frame 2 refused: an element matching the forbidden selector ".my-plugin-api-key" is visible, so it would be in the picture. Close or hide it before the shot, or remove the selector from demo.forbiddenSelectors if it is allowed here.
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
The default vault is the plugin's own seed vault, so a film made without any of this does not film a vault from outside the plugin. Obsidian's standard font is used; nothing pins a font.
|
|
226
|
+
|
|
227
|
+
## What `opdk demo` does
|
|
228
|
+
|
|
229
|
+
`opdk demo [names...]` reads `<demo.outDir>/films/<name>/manifest.json` (default `.opdk/demo`) and writes, for each complete film, into the output folder (`docs/screens` by default, where the three plugins keep their media):
|
|
230
|
+
|
|
231
|
+
| File | What it is |
|
|
232
|
+
|---|---|
|
|
233
|
+
| `<name>.mp4` | x264, yuv420p, crf 20, `-preset slow`, faststart, even dimensions, at the film's fps |
|
|
234
|
+
| `<name>.gif` | its own palette (`palettegen stats_mode=diff`, bayer dithering), 128 colours, 10 fps (the film's fps when that is lower), as wide as the frames up to 1000 px, never upscaled |
|
|
235
|
+
| `<name>-poster.png` | the film's first frame at the frame's resolution, so a site's `<video poster>` is as sharp as the video |
|
|
236
|
+
|
|
237
|
+
Without names every complete film is encoded and every still is copied. A name selects the film and the still of that name (both, when a film and a still share it), and only those: `opdk demo hero` copies the still `hero` and encodes no film, `opdk demo tour` encodes the film `tour` and copies no still. A name that is neither a film nor a still fails (with stills turned off, a still's name is not known, and the error adds `demo.stills is false, so stills are not selectable`). A run that has stills and no film copies them without needing ffmpeg. A still never replaces a film's file, written in the same run or recorded as the film's by an earlier one: a still named `tour-poster` next to the film `tour` fails with `still "tour-poster" would overwrite the poster of film "tour"; rename the still`, and the poster stays. Every file a run writes, stills included, is recorded in `<outDir>/published.json` for the stale-media check, which names a recorded file that is still on disk when its film or still is gone, or when its film or still was written without a failure in this run but not this file (an output turned off with `mp4: false`, or moved with `demo.output` or `demo.stills.output`). A film's file is encoded to a temporary name in a work folder and moved into the output folder when it is complete; a still is copied to `<name>.png.opdk-partial` next to its destination and renamed. Either way a failure leaves the previous good file. The command never deletes media. Frames go through ffmpeg's concat demuxer with a duration per frame; the last frame is listed again, so its whole hold plays, and the encode is capped at the sum of the holds.
|
|
238
|
+
|
|
239
|
+
### The phone layout
|
|
240
|
+
|
|
241
|
+
`layout: "phone-captions"` puts each phone frame on a 1000 x 620 CSS page at 2x (2000 x 1240 px): the phone, with rounded corners and a shadow, on the left, and the caption list on the right with the current step lit and the others dimmed. The heading is `phone.title`. Colours come from `phone` (`background`, `text`, `muted`, `accent`, `font`). Flat colours apply to every film. The `light` and `dark` entries apply only to films recorded inside `demo.themes()` and override the flat colours for that theme; a film without a theme uses the flat colours over the light defaults. Captions and the heading are HTML-escaped. A colour or font value that could end the CSS rule or start an escape, a comment or a request (`;` `{` `}` `<` `>` `\` `/*` `url(`) is rejected, and so are quotes in a colour.
|
|
242
|
+
|
|
243
|
+
The page is rendered in a bare hidden Electron window from the plugin's own `electron` devDependency, driven by Playwright, loaded only for this layout: about 2 s plus 0.1 s per frame. A missing `electron` or `@playwright/test` says what to install, and a step that hangs for 30 s fails the film. It needs no Python and no ffmpeg `drawtext`.
|
|
244
|
+
|
|
245
|
+
### Checks
|
|
246
|
+
|
|
247
|
+
| Check | What it says | Severity |
|
|
248
|
+
|---|---|---|
|
|
249
|
+
| ffmpeg | found through `OPDK_FFMPEG` when set (no fallback), otherwise `PATH`, and (for the MP4) `libx264` is checked before any work, with the install command in the message | fails |
|
|
250
|
+
| ffmpeg errors | a non-zero exit fails the film with the tail of stderr, and so does an exit 0 that printed errors (ffmpeg exits 0 after skipping a frame it cannot decode); an encode that runs for 10 minutes is killed | fails |
|
|
251
|
+
| size | a file above 2 MB warns, above 10 MB fails (GitHub's limit for images and GIFs attached to issues and pull requests); `budget` changes both | warns, fails |
|
|
252
|
+
| loop | the film's last recorded frame should equal its first, or the GIF jumps when it repeats; pixels whose channels differ by 8 of 255 or less count as equal, and the warning names the box and share of the pixels that differ more | warns; `loop: "fail"` fails, `"off"` skips |
|
|
253
|
+
| short holds | a frame held for less than one GIF frame can be skipped; the warning names the frame | warns |
|
|
254
|
+
| density | frames shot below scale 2, or a frame size that does not match the scale | warns |
|
|
255
|
+
| stale media | media this command wrote on an earlier run (recorded in `<outDir>/published.json`) that is still on disk and that no film or still produces any more: its film or still is gone from `<outDir>`, or it was written cleanly in this run without writing the file (an output turned off or moved). A film that failed or was not selected proves nothing about its files. Listed and never deleted | warns |
|
|
256
|
+
| theme pairs | a `-light` or `-dark` film whose partner is missing | warns |
|
|
257
|
+
|
|
258
|
+
Warnings print as `!` lines and leave the exit code alone. Exit 1 on anything that fails: no films and no stills, a name that is neither a film nor a still, an incomplete film named on the command line, without names, no complete film among the recorded films (stills do not make up for it), a still that cannot be copied or would overwrite a file a film wrote now or in an earlier run, an unusable manifest, a missing ffmpeg, an encode, a file over the fail limit and `loop: "fail"`.
|
|
259
|
+
|
|
260
|
+
### Example output
|
|
261
|
+
|
|
262
|
+
The kit's own film (`npm run docs:media:demo`), a run of two stills (the first changed since the last run, the second did not), then two failures:
|
|
263
|
+
|
|
264
|
+
```text
|
|
265
|
+
$ opdk demo demo
|
|
266
|
+
· demo demo: composing 8 frames beside their captions in Electron
|
|
267
|
+
✓ demo demo: gif 141 KB
|
|
268
|
+
$ opdk demo hero settings
|
|
269
|
+
✓ demo still hero: png 312 KB
|
|
270
|
+
· demo 1 still unchanged: settings
|
|
271
|
+
$ opdk demo nosuch
|
|
272
|
+
✗ demo no film or still named "nosuch" in /path/to/plugin/.opdk/demo
|
|
273
|
+
Films there: demo
|
|
274
|
+
Stills there: hero, settings
|
|
275
|
+
Run the demo specs first (npx playwright test), or fix the name.
|
|
276
|
+
$ OPDK_FFMPEG=/nonexistent/ffmpeg opdk demo
|
|
277
|
+
✗ opdk: command "demo" failed: OPDK_FFMPEG=/nonexistent/ffmpeg cannot run (/nonexistent/ffmpeg could not run (spawn /nonexistent/ffmpeg ENOENT).). Point it at a working ffmpeg binary or unset it to use PATH.
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
A film that was renamed or deleted leaves its files behind, and the next run says so:
|
|
281
|
+
|
|
282
|
+
```text
|
|
283
|
+
! demo media published by an earlier run of this command belongs to films or stills that no longer exist: docs/screens/old-name.gif, docs/screens/old-name.mp4. Delete them if they are obsolete; the command never removes files.
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
Only files `opdk demo` itself wrote are named. The record is `<outDir>/published.json` (output path to film name); it is created by the first run, so a project that has just updated sees no stale warning until its films have been encoded once. A file that was deleted drops out of the record on the next run. Unrelated pictures in the output folder are never listed. The record sits in `outDir`, next to the raw frames, and is not meant to be committed.
|
|
287
|
+
|
|
288
|
+
## Configuration
|
|
289
|
+
|
|
290
|
+
The `demo` section of `opdk.config.mjs`. Every key is optional, an unknown key fails and names itself. The film keys can be set for all films at the top level or for one film under `films.<name>`; a more specific value wins.
|
|
291
|
+
|
|
292
|
+
| Key | Type | Default | Meaning |
|
|
293
|
+
|---|---|---|---|
|
|
294
|
+
| `outDir` | string | `.opdk/demo` | Where the fixture wrote films. The same default as the fixture's `demo.outDir`; set both when you change it |
|
|
295
|
+
| `output` | string | `docs/screens` | Where finished media go, relative to the plugin root |
|
|
296
|
+
| `stills` | `{ output? }` or boolean | `true`, copied to `output` | Publishes `<outDir>/stills/<name>.png` as `<output>/<name>.png`, when the bytes differ. `false` turns it off, `output` is a separate folder. Top level only: a still belongs to no film |
|
|
297
|
+
| `outputs` | `Record<string, string>` | none | Named folders for stills, relative to the plugin root: `{ listing: "docs/listing" }`. A still recorded with `{ out: "listing" }` is copied there. Names are one path segment. Top level only |
|
|
298
|
+
| `gif` | `{ width?, colors?, fps? }` or `false` | 128 colours, 10 fps at most, width of the frames up to 1000 | `width` 16 to 8000 (not upscaled; a wider value warns), `colors` 2 to 256, `fps` 1 to 50 (used as given). `false` skips the GIF |
|
|
299
|
+
| `mp4` | boolean | `true` | `false` skips the MP4 |
|
|
300
|
+
| `poster` | `{ width? }`, boolean | `true`, the frame's resolution | `false` skips the poster |
|
|
301
|
+
| `layout` | `"plain"` or `"phone-captions"` | `"plain"` | `"phone-captions"` is for phone films with `captions` |
|
|
302
|
+
| `budget` | `{ warnBytes?, failBytes? }` | 2 MB, 10 MB | Per file. `warnBytes` must not be above `failBytes` |
|
|
303
|
+
| `loop` | `"warn"`, `"fail"`, `"off"` | `"warn"` | What to do when the last frame differs from the first |
|
|
304
|
+
| `phone` | object | neutral light and dark colours | `background`, `text`, `muted`, `accent`, `font`, `title`, and `light` and `dark` objects with the four colours |
|
|
305
|
+
| `films` | object keyed by film name | none | The same film keys, for one film. A theme pair reads the entry of its base name, the exact name wins |
|
|
306
|
+
|
|
307
|
+
The options of the `demo` fixture (`createObsidianTest({ demo })`):
|
|
308
|
+
|
|
309
|
+
| Key | Type | Default | Meaning |
|
|
310
|
+
|---|---|---|---|
|
|
311
|
+
| `outDir` | string | `.opdk/demo` | Where films and stills are written, relative to the directory `playwright test` runs in |
|
|
312
|
+
| `scale` | whole number 1 to 4 | 2 | Device pixels per CSS pixel |
|
|
313
|
+
| `forbiddenSelectors` | string[] | none | CSS selectors that must never be visible in a picture |
|
|
314
|
+
|
|
315
|
+
### Environment variables
|
|
316
|
+
|
|
317
|
+
| Variable | Meaning |
|
|
318
|
+
|---|---|
|
|
319
|
+
| `OPDK_FFMPEG` | Path of the ffmpeg binary; when set it is used with no fallback to `PATH` |
|
|
320
|
+
| `OPDK_COMPOSE_NO_SANDBOX` | `1` starts the Electron that draws the phone layout with `--no-sandbox`, for machines where Chromium's sandbox cannot start (a CI runner). The kit's CI sets it |
|
|
321
|
+
| `OPDK_E2E_VAULT` | Replaces the seed vault; the demo fixture then refuses to capture unless the call passes `allowForeignVault: true` |
|
|
322
|
+
| `OPDK_DEBUG` | `1` prints the stack of a failed command |
|
|
323
|
+
|
|
324
|
+
## CI
|
|
325
|
+
|
|
326
|
+
A film needs the real Obsidian, so recording belongs on a machine that has it. `opdk demo` itself needs ffmpeg, and, for the phone layout, Electron and a display. The kit's own `ci.yml` runs the encoder and layout tests this way on `ubuntu-latest`:
|
|
327
|
+
|
|
328
|
+
- install ffmpeg and a virtual display: `sudo apt-get install -y --no-install-recommends ffmpeg xvfb xauth`;
|
|
329
|
+
- download the Electron binary once (`node node_modules/electron/install.js`), cached by lockfile (`~/.cache/electron`);
|
|
330
|
+
- run the step under `xvfb-run -a` with `OPDK_COMPOSE_NO_SANDBOX: "1"`.
|
|
331
|
+
|
|
332
|
+
## Migrating from a plugin's own scripts
|
|
333
|
+
|
|
334
|
+
1. Install the kit, ffmpeg and (for the e2e fixture) the e2e dependencies ([docs/e2e.md](e2e.md)). Add `.opdk/` to `.gitignore`. To move the kit to a newer tag run `npm install -D "github:Dimagious/obsidian-plugin-dev-kit#<tag>"`. Editing the tag in `package.json` and running a plain `npm install` keeps the old entry in `package-lock.json`, and the old version stays installed.
|
|
335
|
+
2. Rewrite the recording specs on the `demo` fixture: a film of stills (`demo.film`, `film.shot`) in place of a screen recording or a screenshot loop, `demo.moveAndClick`, `demo.tap`, `demo.typeSlowly`, `demo.caption`, `demo.cleanUi`, `demo.freezeTime`, `demo.themes`.
|
|
336
|
+
3. Move the encoding settings to the `demo` section of `opdk.config.mjs` and delete the plugin's encoder script.
|
|
337
|
+
Pictures for the README or the listing that a script takes with `win.screenshot()` move to `demo.still(name, { preset })`; `opdk demo` then puts them in the output folder, and their density no longer depends on the display. A `waitForTimeout` before such a picture becomes `settle: true` (or `obsidian.settle()` before an assertion); a pause longer than `quietMs` before the render looks settled, so assert on the element or raise `quietMs`.
|
|
338
|
+
4. Run the specs and `opdk demo`, compare the files with the old ones and list the differences in the plugin's CHANGELOG.
|
|
339
|
+
|
|
340
|
+
What changes for a plugin that had its own scripts. Anything not listed behaves as before.
|
|
341
|
+
|
|
342
|
+
- The poster is `<name>-poster.png` and the output folder `docs/screens`, the names and folder such plugins already used. The theme suffix is `-light` or `-dark`, as the fixture names themed films. ffmpeg is looked up through `OPDK_FFMPEG` first. A film is only encoded when its recording finished.
|
|
343
|
+
- The GIF defaults (128 colours, 10 fps at most, as wide as the frames up to 1000 px) replace each script's own numbers, which are now `gif` options per film. To keep your old output, copy its numbers: for example `gif: { colors: 256, fps: 4, width: 760 }`, or `gif: { fps: 12, width: 720 }`. The dither is the kit's (`stats_mode=diff`, bayer scale 5, `diff_mode=rectangle`), so only the numbers change.
|
|
344
|
+
- README and listing pictures taken with plain `win.screenshot` have the display's density. They move to `demo.still(name, { preset, settle: true })` (2x on any monitor, exactly the pixels of the destination), and `opdk demo` copies them to the output folder; a fixed `waitForTimeout` before such a picture becomes `settle: true` (a pause longer than `quietMs` before the render looks settled, so assert on the element or raise `quietMs`). Pictures that were committed from a 1x or a 2x display change size, so list them in the plugin's CHANGELOG.
|
|
345
|
+
- `beat()` takes seconds, not milliseconds. The helpers no longer pause by themselves: pacing is `beat()` for a Playwright video of a test and `hold` for films of stills.
|
|
346
|
+
- A phone film's MP4, GIF and poster come from the one command. The poster is the first frame (2000 x 1240). The GIF is made for the dark film too; set `gif: false` on the dark film to keep a light GIF only. The GIF is 10 fps at most by default: set `gif: { fps: 15 }` to keep a 15 fps phone GIF.
|
|
347
|
+
- The composed page (a phone with a lit step beside a list) is drawn from `phone`. The phone height is 540 px, and the heading and steps are the film's `title` and `captions`; a caption with a line break gives a heading and a text. The text is HTML-escaped.
|
|
348
|
+
- The kit renders with the plugin's Electron, not with Chrome through Playwright.
|
|
349
|
+
- A poster named `film-<name>-poster.png` keeps its name if the film is named `film-<name>`.
|
|
350
|
+
- A failed ffmpeg is not a warning: it fails the film (a script that used `set -euo pipefail` already stopped).
|
|
351
|
+
- If your runs point at a generated vault through `OPDK_E2E_VAULT`, note that the demo fixture refuses any set `OPDK_E2E_VAULT`. Make the generated vault the `seedVault`, or pass `allowForeignVault: true`.
|
|
352
|
+
- A script that composed voice-over and an outro: the kit does neither (no audio, no intro or outro cards), so only the film-to-media step moves.
|
|
353
|
+
- A demo recorded as a video of the window is shot again as a silent film of stills.
|
|
354
|
+
|
|
355
|
+
## Limits today
|
|
356
|
+
|
|
357
|
+
- Films are made of stills. There is no recording of the window as video, so an animation that matters (a spinner, a transition) shows as the frame the shot froze.
|
|
358
|
+
- No audio, no voice-over, no intro or outro cards.
|
|
359
|
+
- Verified on macOS with Obsidian 1.14.5. Capture on Linux CI is not built; the kit's CI runs only the encoder and the layout tests there. Windows is untested.
|
|
360
|
+
- The fixture records one window. Films in several languages are not covered.
|
|
361
|
+
- A retake is not byte-identical: pictures come from a real Obsidian, so a pixel here and there can differ between runs.
|
|
362
|
+
- `freezeTime` does not freeze the file dates in the explorer, and code that measures elapsed time sees none pass.
|
|
363
|
+
- The loop check treats a pixel as equal when each channel differs by at most 8 of 255, so noise below that is not reported. A tour that does not end where it began still warns; see **Loops**.
|
|
364
|
+
- A frame can hold network content (a page that loads data when it runs, a remote image), which differs between takes and can fail the loop check. For a stable film replace the plugin's fetching function with `obsidian.replace()` and return fixture data ([docs/e2e.md](e2e.md)).
|