@mnaoumov/create-obsidian-plugin 0.0.0-stage → 1.0.0

package/templates/default/scripts/vitest-config.ts.ejs

@@ -0,0 +1,75 @@
+import type { ObsidianPluginVitestConfigContext } from 'obsidian-dev-utils/script-utils/test-runners/vitest-config';
+import type { TestProjectConfiguration } from 'vitest/config';
+
+import { fileURLToPath } from 'node:url';
+import { defineObsidianPluginVitestConfig } from 'obsidian-dev-utils/script-utils/test-runners/vitest-config';
+
+/**
+ * The demo-vault button suite. It drives a real desktop Obsidian like the desktop project, but opens a
+ * copy of the in-repo `demo-vault/` rather than an empty vault — hence its own `globalSetup` — and needs
+ * its own file suffix so the desktop project does not also collect it and open it against a vault with no
+ * notes in it.
+ */
+const DEMO_VAULT_TEST_FILES = 'src/**/*.demo-vault.integration.test.ts';
+
+/**
+ * One `it` per note runs every button in that note, and each button re-opens the note, walks the preview
+ * to find itself and then waits for a result. A note with several buttons blows past the desktop
+ * project's 30s default — which fails the whole note with a bare vitest timeout instead of naming the
+ * button that actually misbehaved.
+ */
+const DEMO_VAULT_TIMEOUT_IN_MILLISECONDS = 600_000;
+
+/**
+ * Where every `.svelte` / `.vue` import in a unit test's module graph is sent. Compiling a single-file
+ * component is the bundler's job, and the plugin that does it is a dependency only of the bundler that
+ * was chosen — so a unit test that imports the plugin's own code would otherwise fail on a file vitest
+ * cannot transform. Absolute, because a vite alias replacement is resolved from the project root rather
+ * than from this file.
+ */
+const FRAMEWORK_COMPONENT_STUB_PATH = fileURLToPath(new URL('framework-component-stub.ts', import.meta.url));
+
+/**
+ * Where every `.wasm` import in a unit test's module graph is sent, for the same reason as the component
+ * stub above. Vitest resolves a `.wasm` through vite's own WebAssembly helper, which fetches it from a
+ * URL that exists only under a dev server — so a unit test that imports the plugin's own code fails on
+ * `Failed to parse URL` before it runs a single assertion.
+ */
+const WASM_MODULE_STUB_PATH = fileURLToPath(new URL('wasm-module-stub.ts', import.meta.url));
+
+/**
+ * Where every stylesheet import in a unit test's module graph is sent. `src/main.ts` imports one for its
+ * side effect, and on the `tailwind` styling the file it names is generated by the first build — so a
+ * unit test run on a fresh clone would otherwise fail to resolve it.
+ */
+const STYLESHEET_STUB_PATH = fileURLToPath(new URL('stylesheet-stub.ts', import.meta.url));
+
+export const config = defineObsidianPluginVitestConfig({
+  customProjects(context: ObsidianPluginVitestConfigContext): TestProjectConfiguration[] {
+    return [
+      {
+        test: {
+          ...context.desktop,
+          globalSetup: ['./scripts/demo-vault-global-setup.ts'],
+          include: [DEMO_VAULT_TEST_FILES],
+          name: 'integration-tests:demo-vault',
+          testTimeout: DEMO_VAULT_TIMEOUT_IN_MILLISECONDS
+        }
+      }
+    ];
+  },
+  // `^.+` is load-bearing, not decoration: a vite alias built from a RegExp replaces only the part the
+  // Pattern MATCHED, so `/\.svelte$/` rewrites the extension and leaves the rest of the specifier glued
+  // To the front of the stub path. The pattern has to cover the whole id.
+  editContext(context: ObsidianPluginVitestConfigContext): void {
+    context.unitTests.alias = [
+      { find: /^.+\.(?:svelte|vue)$/u, replacement: FRAMEWORK_COMPONENT_STUB_PATH },
+      { find: /^.+\.(?:css|scss)$/u, replacement: STYLESHEET_STUB_PATH },
+      // Two patterns because two bundlers do not write the import plainly: vite asks for the asset's URL
+      // (`./module.wasm?url`) and parcel uses a scheme (`data-url:./module.wasm`).
+      { find: /^.+\.wasm(?:\?.*)?$/u, replacement: WASM_MODULE_STUB_PATH },
+      { find: /^data-url:.+$/u, replacement: WASM_MODULE_STUB_PATH }
+    ];
+  }
+});
+<%- render('post-config') -%>

package/templates/default/scripts/vitest-config.ts@post-config_solid.ejs

@@ -0,0 +1,67 @@
+
+/**
+ * The config above, narrowed to the one field this file writes through.
+ */
+interface ConfigWithProjects {
+  test: ProjectsSection;
+}
+
+/**
+ * The shape of a project entry this file reaches into, which vitest's own union type does not narrow to.
+ */
+interface JsxProject {
+  oxc?: OxcSection;
+}
+
+/**
+ * The JSX transform a test project is given.
+ *
+ * Deliberately not named `…Options`: the shared lint config requires every member of a `Params` /
+ * `Options` / `Result` interface to be `readonly`, and this one is assigned to.
+ */
+interface JsxRuntimeSpec {
+  importSource: string;
+  runtime: string;
+}
+
+/**
+ * The `oxc` section of a project entry.
+ */
+interface OxcSection {
+  jsx: JsxRuntimeSpec;
+}
+
+/**
+ * The `test` section of the config above.
+ */
+interface ProjectsSection {
+  projects: JsxProject[];
+}
+
+/*
+ * Solid compiles its JSX with `babel-preset-solid`, so the project's `tsconfig.json` sets
+ * `jsx: 'preserve'` and leaves the JSX in place for the bundler. Vite refuses to parse a file in that
+ * state at all -- "make sure to not set jsx to preserve" -- so every suite whose module graph reaches a
+ * `.tsx` file fails before it runs. The test projects transform JSX with the automatic runtime instead,
+ * from `solid-js/h`, which is the entry point that publishes a `jsx-runtime`; plain `solid-js` does not.
+ * Reactivity is not compiled in, which unit tests do not need -- rendering a Solid component is an
+ * integration-test job.
+ *
+ * Applied here rather than through `editContext`, which reaches a project's `test` section only, while
+ * `oxc` is a vite-level option on the project itself.
+ *
+ * Widened through a separate `unknown` binding rather than asserted twice in one expression: the
+ * returned type does not overlap `ConfigWithProjects`, so a direct assertion is TS2352, and
+ * `as unknown as` in one expression is what the shared lint config bans.
+ */
+const untypedConfig: unknown = config;
+const configWithProjects = untypedConfig as ConfigWithProjects;
+
+for (const project of configWithProjects.test.projects) {
+  project.oxc = {
+    jsx: {
+      importSource: 'solid-js/h',
+      runtime: 'automatic'
+    }
+  };
+}

package/templates/default/scripts/wasm-module-stub.ts.ejs

@@ -0,0 +1,21 @@
+/**
+ * The unit runners' stand-in for a `.wasm` import.
+ *
+ * Neither runner can load one the way the bundler does, and each fails differently: vitest resolves a
+ * `.wasm` through vite's own WebAssembly helper, which tries to `fetch` it from a URL that does not
+ * exist outside a dev server, and jest has no transform for the extension at all. Meanwhile the emitted
+ * `src/plugin.ts` reaches the module through `src/wasm/sample-command.ts`, so ANY unit test that imports
+ * the plugin -- which the sample one does, deliberately -- pulls the `.wasm` into its module graph.
+ *
+ * So both runners send every `.wasm` import here, exactly as they send every `.svelte` / `.vue` import
+ * to `framework-component-stub.ts`, and for the same reason: loading the real thing is the bundler's
+ * job, and no unit test needs it.
+ *
+ * It throws rather than returning inert bytes. A unit test that really does want to run WebAssembly
+ * should instantiate the module itself from `readFileSync`, and this sentence is what tells it so.
+ *
+ * @throws Always.
+ */
+export default function wasmModuleStub(): never {
+  throw new Error('A `.wasm` import is not loaded in unit tests. Read the file and instantiate it directly if a test needs the real module.');
+}

package/templates/default/scripts/webpack.config.ts.ejs

@@ -0,0 +1,124 @@
+import type { Configuration } from 'webpack';
+
+<%# Sorted as one group: the per-answer partials contribute imports in question-registration order, -%>
+<%# which is not the order an import-sorting lint rule wants. See `sortImports` in `src/templates.ts`. -%>
+<%- sortImports(`import { builtinModules } from 'node:module';
+import { join } from 'node:path';
+import process from 'node:process';
+import TerserPlugin from 'terser-webpack-plugin';
+${render('lint-webpack-default')}import webpack from 'webpack';
+${render('import')}`) -%>
+
+const isProduction = process.env['BUILD'] === 'production';
+const distFolder = process.env['DIST_FOLDER'] ?? (isProduction ? 'dist/build' : 'dist/dev');
+
+const EXTERNAL = [
+  'obsidian',
+  'electron',
+  '@codemirror/autocomplete',
+  '@codemirror/collab',
+  '@codemirror/commands',
+  '@codemirror/language',
+  '@codemirror/lint',
+  '@codemirror/search',
+  '@codemirror/state',
+  '@codemirror/view',
+  '@lezer/common',
+  '@lezer/highlight',
+  '@lezer/lr',
+  'esbuild',
+  'eslint',
+  ...builtinModules
+];
+
+<%# Each per-answer partial ends its entry with a comma so two of them concatenate into a valid list; -%>
+<%# the last entry of each array must not carry one. Stripped here rather than by making every partial -%>
+<%# know whether it is last. -%>
+<%
+  const rules = `      {
+        // The emitted \`tsconfig.json\` declares \`noEmit: true\` and allows \`.ts\` import specifiers, both
+        // Right for the file itself -- more than tsc reads it. ts-loader compiles WITH emit, so it needs
+        // Both overridden, and the overrides belong here, in the one tool that needs them, exactly as
+        // \`jest.config.ts\` overrides \`rootDir\` for the same reason.
+        //
+        // \`rewriteRelativeImportExtensions\` rather than turning \`allowImportingTsExtensions\` off: the
+        // Emitted \`src/\` really does import \`./plugin.ts\` by that name, so switching it off trades
+        // TS5096 for an error on every one of those. This is the option TypeScript added for emitting
+        // From exactly such sources. \`onlyCompileBundledFiles\` keeps ts-loader to the graph webpack
+        // Actually pulls in, instead of every file the tsconfig's \`include\` lists -- it was reaching
+        // \`webpack.config.ts\` and \`scripts/dev.ts\`, which are no business of the bundle.
+        exclude: /node_modules/,
+        test: /\\.tsx?$/,
+        use: {
+          loader: 'ts-loader',
+          options: {
+${render('ts-loader-options')}            compilerOptions: {
+              noEmit: false,
+${render('ts-loader-compiler-options')}              rewriteRelativeImportExtensions: true
+            },
+            onlyCompileBundledFiles: true
+          }
+        }
+      },
+${render('rule')}`;
+  const plugins = `    new webpack.BannerPlugin({
+      banner: \`/*
+THIS IS A GENERATED/BUNDLED FILE BY WEBPACK
+if you want to view the source, please visit the github repository of this plugin
+*/\`,
+      raw: true
+    }),
+${render('plugin')}`;
+-%>
+export const config: Configuration = {
+  devtool: isProduction ? false : 'inline-source-map',
+  entry: './src/main.ts',
+  externals: Object.fromEntries(
+    EXTERNAL.map((moduleName) => [moduleName, `commonjs2 ${moduleName}`])
+  ),
+  mode: isProduction ? 'production' : 'development',
+  module: {
+    rules: [
+<%- rules.replace(/,(?<Trailing>\s*)$/, '$<Trailing>') -%>
+    ]
+  },
+  optimization: {
+    // Terser's default `extractComments` cuts every bundled dependency's `/*! ... */` and `@license`
+    // Comment out of `main.js` into a `main.js.LICENSE.txt` beside it -- which no Obsidian release ships,
+    // So the installed plugin would carry the code without the notices it is licensed under. Kept inline
+    // Instead, as esbuild's `legalComments` default keeps them.
+    minimizer: [new TerserPlugin({ extractComments: false })]
+  },
+  output: {
+    // An Obsidian release ships `main.js` and nothing beside it, so a dynamic import -- obsidian-dev-utils
+    // Has several -- must not become a sibling chunk that `main.js` then loads by name at runtime. This is
+    // Webpack's twin of rollup's `inlineDynamicImports`.
+    asyncChunks: false,
+    filename: 'main.js',
+    libraryExport: 'default',
+    libraryTarget: 'commonjs2',
+    path: join(process.cwd(), distFolder)
+  },
+  plugins: [
+<%- plugins.replace(/,(?<Trailing>\s*)$/, '$<Trailing>') -%>
+  ],
+  resolve: {
+    // A plugin runs in Obsidian's renderer, not in Node, but `target: 'node'` resolves only the `node`
+    // Export condition -- which hands Solid and Svelte their SERVER builds, where `render` / `mount` do
+    // Nothing a view can use, with the build green. `browser` is what esbuild's `conditions` and rollup's
+    // `nodeResolve({ browser: true })` already ask for; `'...'` keeps webpack's own defaults beside it.
+    conditionNames: ['browser', '...'],
+    // The loader above rewrites `./plugin.ts` to `./plugin.js` on emit, but only `./plugin.ts` exists on
+    // Disk, and webpack's `extensions` list only appends a suffix to a request that has no extension --
+    // It does not map one extension to another. Without this the bundle fails to resolve "./plugin.js".
+    //
+    // Under `jsx: preserve` (the Solid answer) it rewrites `./view.tsx` to `./view.jsx` instead, so that
+    // Name is mapped back the same way. Nothing else emits a `.jsx` specifier, so elsewhere it is inert.
+    extensionAlias: {
+      '.js': ['.ts', '.tsx', '.js'],
+      '.jsx': ['.tsx', '.jsx']
+    },
+    extensions: ['.ts', '.tsx', '.js']
+  },
+  target: 'node'
+};

package/templates/default/scripts/webpack.config.ts@import_svelte.ejs

@@ -0,0 +1 @@
+import { sveltePreprocess } from 'svelte-preprocess';

package/templates/default/scripts/webpack.config.ts@import_vue.ejs

@@ -0,0 +1 @@
+import { VueLoaderPlugin } from 'vue-loader';

package/templates/default/scripts/webpack.config.ts@import_webpack-css-extract.ejs

@@ -0,0 +1,4 @@
+<%# Shared by EVERY styling answer that extracts CSS, rather than one identical copy per answer. -%>
+<%# Partials are a Set, so a preset forcing a second styling answer on top of the chosen one -- which -%>
+<%# `demo` does, with `scss` -- renders this once instead of emitting a duplicate `import` (TS2300). -%>
+import MiniCssExtractPlugin from 'mini-css-extract-plugin';

package/templates/default/scripts/webpack.config.ts@lint-webpack-default_dev-utils.ejs

@@ -0,0 +1 @@
+// eslint-disable-next-line import-x/no-named-as-default -- The default export IS the `webpack` namespace; the same name is the point.

package/templates/default/scripts/webpack.config.ts@plugin_vue.ejs

@@ -0,0 +1 @@
+    new VueLoaderPlugin(),

package/templates/default/scripts/webpack.config.ts@plugin_webpack-css-extract.ejs

@@ -0,0 +1,4 @@
+<%# One instance, for the reason its import partial gives: two plugins both writing `styles.css` is -%>
+<%# what five per-answer copies produced. The per-answer `rule` partials stay per-answer -- they test -%>
+<%# different extensions and are meant to coexist. -%>
+    new MiniCssExtractPlugin({ filename: 'styles.css' }),

package/templates/default/scripts/webpack.config.ts@rule_css-modules.ejs

@@ -0,0 +1,7 @@
+      {
+        test: /\.module\.css$/,
+        use: [
+          MiniCssExtractPlugin.loader,
+          { loader: 'css-loader', options: { modules: true } }
+        ]
+      },

package/templates/default/scripts/webpack.config.ts@rule_css.ejs

@@ -0,0 +1,4 @@
+      {
+        test: /\.css$/,
+        use: [MiniCssExtractPlugin.loader, 'css-loader']
+      },

package/templates/default/scripts/webpack.config.ts@rule_postcss.ejs

@@ -0,0 +1,4 @@
+      {
+        test: /\.css$/,
+        use: [MiniCssExtractPlugin.loader, 'css-loader', 'postcss-loader']
+      },

package/templates/default/scripts/webpack.config.ts@rule_scss.ejs

@@ -0,0 +1,4 @@
+      {
+        test: /\.scss$/,
+        use: [MiniCssExtractPlugin.loader, 'css-loader', 'sass-loader']
+      },

package/templates/default/scripts/webpack.config.ts@rule_solid.ejs

@@ -0,0 +1,17 @@
+<%# Solid's JSX is not React's, so ts-loader leaves it alone: the Solid answer sets `jsx: preserve` for -%>
+<%# `babel-preset-solid`, and ts-loader emits every `.tsx` with its JSX intact. This rule compiles it. -%>
+<%# `enforce: 'post'` runs it AFTER ts-loader, which still type-checks and strips the types, so babel -%>
+<%# needs only the Solid preset. `configFile: false` keeps a babel config another answer emits away from it. -%>
+      {
+        enforce: 'post',
+        exclude: /node_modules/,
+        test: /\.tsx$/,
+        use: {
+          loader: 'babel-loader',
+          options: {
+            babelrc: false,
+            configFile: false,
+            presets: ['babel-preset-solid']
+          }
+        }
+      },

package/templates/default/scripts/webpack.config.ts@rule_svelte.ejs

@@ -0,0 +1,7 @@
+      {
+        test: /\.svelte$/,
+        use: {
+          loader: 'svelte-loader',
+          options: { preprocess: sveltePreprocess() }
+        }
+      },

package/templates/default/scripts/webpack.config.ts@rule_tailwind.ejs

@@ -0,0 +1,4 @@
+      {
+        test: /\.css$/,
+        use: [MiniCssExtractPlugin.loader, 'css-loader']
+      },

package/templates/default/scripts/webpack.config.ts@rule_vue.ejs

@@ -0,0 +1,4 @@
+      {
+        test: /\.vue$/,
+        use: 'vue-loader'
+      },

package/templates/default/scripts/webpack.config.ts@rule_wasm.ejs

@@ -0,0 +1,8 @@
+      {
+        // NOT `experiments.asyncWebAssembly`, which is what this used to be. That emits the module as a
+        // Separate `.wasm` chunk the bundle fetches at runtime -- and an Obsidian release ships `main.js`
+        // And `styles.css` and nothing else, so the chunk is simply absent wherever the plugin is
+        // Installed. `asset/inline` carries the module inside `main.js` as a `data:` URL instead.
+        test: /\.wasm$/,
+        type: 'asset/inline'
+      },

package/templates/default/scripts/webpack.config.ts@ts-loader-compiler-options_vue.ejs

@@ -0,0 +1,5 @@
+<%# Only for this compile, not in `tsconfig.json`. `appendTsSuffixTo` hands ts-loader the component's -%>
+<%# `<script>` block as a standalone module, WITHOUT the template that uses its bindings, so every -%>
+<%# handler the template calls reads as unused: TS6133 "'increment' is declared but its value is never -%>
+<%# read". The gate's own `tsc --noEmit`, and the editor, still enforce it on real `.ts` files. -%>
+              noUnusedLocals: false,

package/templates/default/scripts/webpack.config.ts@ts-loader-options_vue.ejs

@@ -0,0 +1,5 @@
+<%# Without this, ts-loader does not recognize vue-loader's `?vue&type=script&lang=ts` request as -%>
+<%# TypeScript, and TypeScript resolves the block against the WRONG file: the build failed with -%>
+<%# "Can't resolve './styles/main.module.css' in src/vue-components" -- which is `src/main.ts`'s import, -%>
+<%# reported from the component's directory. -%>
+            appendTsSuffixTo: [/\.vue$/u],

package/templates/default/src/demo-vault-buttons.demo-vault.integration.test.ts.ejs

@@ -0,0 +1,12 @@
+import { registerDemoVaultButtonSuite } from 'obsidian-dev-utils/script-utils/demo-vault-buttons';
+
+// Clicks every `code-button` in `demo-vault/` against a real Obsidian. A button fails at CLICK time -- a
+// Wrong `require('/demoSetup.ts')` path, or an API that changed shape under it -- so no other gate can
+// Catch it: `lint:md` reads the markdown and the coverage suite checks the authoring conventions, and
+// Neither executes anything.
+//
+// It needs the CodeScript Toolkit binary seeded into `demo-vault/.obsidian/plugins/`, which happens the
+// First time you open `demo-vault/` in Obsidian. See CONTRIBUTING.md.
+//
+// Isolation: `npx vitest run --project integration-tests:demo-vault`.
+registerDemoVaultButtonSuite();

package/templates/default/src/demo-vault.no-app.integration.test.ts.ejs

@@ -0,0 +1,18 @@
+import process from 'node:process';
+import { registerDemoVaultCoverageSuite } from 'obsidian-dev-utils/script-utils/demo-vault-coverage';
+import { getRootFolder } from 'obsidian-dev-utils/script-utils/root';
+
+// Keeps the in-repo `demo-vault/` honest WITHOUT launching Obsidian. It enforces the authoring convention
+// Every vault owes its readers: an `# H1` and a prose opener on every note, Markdown links rather than
+// Wikilinks (which do not render on GitHub), no `[Docs]` line, every note reachable from `00 Start.md`,
+// And an `.obsidian/app.json` that commits none of the settings obsidian-dev-utils injects at release time.
+//
+// `rootFolder` alone is enough for those. Once your settings surface settles, add a reflection spec so the
+// Suite also fails when a setting is documented nowhere in the vault, or when a note names one that no
+// Longer exists:
+//
+// registerDemoVaultCoverageSuite({
+//   configInterfaces: [{ interfaceName: 'PluginSettings', sourcePath: 'src/plugin-settings.ts' }],
+//   rootFolder: getRootFolder() ?? process.cwd()
+// });
+registerDemoVaultCoverageSuite({ rootFolder: getRootFolder() ?? process.cwd() });

package/templates/default/src/editor-extensions/sample-state-field.ts_dev-utils.ejs

@@ -0,0 +1,56 @@
+import type {
+  Extension,
+  Transaction
+} from '@codemirror/state';
+import type { DecorationSet } from '@codemirror/view';
+import type { StateFieldSpec } from 'obsidian-dev-utils/codemirror/state-field-spec';
+
+import {
+  RangeSetBuilder,
+  StateField
+} from '@codemirror/state';
+import {
+  Decoration,
+  EditorView
+} from '@codemirror/view';
+
+import { SampleWidget } from './sample-widget.ts';
+
+class SampleStateField implements StateFieldSpec<DecorationSet> {
+  public create(state: Transaction['state']): DecorationSet {
+    return buildDecorations(state);
+  }
+
+  public provide(field: StateField<DecorationSet>): Extension {
+    return EditorView.decorations.from(field);
+  }
+
+  public update(oldState: DecorationSet, transaction: Transaction): DecorationSet {
+    return transaction.docChanged ? buildDecorations(transaction.state) : oldState;
+  }
+}
+
+function buildDecorations(state: Transaction['state']): DecorationSet {
+  const builder = new RangeSetBuilder<Decoration>();
+  const doc = state.doc;
+
+  for (let index = 1; index <= doc.lines; index++) {
+    const line = doc.line(index);
+    const words = line.text.trim().split(/\s+/).filter((w) => w.length > 0);
+
+    if (words.length > 0) {
+      builder.add(
+        line.to,
+        line.to,
+        Decoration.widget({
+          side: 1,
+          widget: new SampleWidget(words.length)
+        })
+      );
+    }
+  }
+
+  return builder.finish();
+}
+
+export const sampleStateField = StateField.define<DecorationSet>(new SampleStateField());

package/templates/default/src/editor-extensions/sample-state-field.ts_standalone.ejs

@@ -0,0 +1,60 @@
+import type {
+  Extension,
+  Transaction
+} from '@codemirror/state';
+import type { DecorationSet } from '@codemirror/view';
+
+import {
+  RangeSetBuilder,
+  StateField
+} from '@codemirror/state';
+import {
+  Decoration,
+  EditorView
+} from '@codemirror/view';
+
+import { SampleWidget } from './sample-widget.ts';
+
+function buildDecorations(state: Transaction['state']): DecorationSet {
+  const builder = new RangeSetBuilder<Decoration>();
+  const doc = state.doc;
+
+  for (let i = 1; i <= doc.lines; i++) {
+    const line = doc.line(i);
+    const words = line.text.trim().split(/\s+/).filter((w) => w.length > 0);
+
+    if (words.length > 0) {
+      builder.add(
+        line.to,
+        line.to,
+        Decoration.widget({
+          side: 1,
+          widget: new SampleWidget(words.length)
+        })
+      );
+    }
+  }
+
+  return builder.finish();
+}
+
+function createSampleStateField(): StateField<DecorationSet> {
+  return StateField.define<DecorationSet>({
+    create(state): DecorationSet {
+      return buildDecorations(state);
+    },
+
+    provide(field: StateField<DecorationSet>): Extension {
+      return EditorView.decorations.from(field);
+    },
+
+    update(oldState: DecorationSet, transaction: Transaction): DecorationSet {
+      if (transaction.docChanged) {
+        return buildDecorations(transaction.state);
+      }
+      return oldState;
+    }
+  });
+}
+
+export const sampleStateField = createSampleStateField();

package/templates/default/src/editor-extensions/sample-view-plugin.ts.ejs

@@ -0,0 +1,66 @@
+import type {
+  DecorationSet,
+  EditorView,
+  PluginSpec,
+  PluginValue,
+  ViewUpdate
+} from '@codemirror/view';
+
+import { RangeSetBuilder } from '@codemirror/state';
+import {
+  Decoration,
+  ViewPlugin
+} from '@codemirror/view';
+
+import { SampleWidget } from './sample-widget.ts';
+
+class SampleViewPlugin implements PluginValue {
+  public decorations: DecorationSet;
+
+  public constructor(view: EditorView) {
+    this.decorations = this.buildDecorations(view);
+  }
+
+  public update(update: ViewUpdate): void {
+    if (update.docChanged || update.viewportChanged) {
+      this.decorations = this.buildDecorations(update.view);
+    }
+  }
+
+  private buildDecorations(view: EditorView): DecorationSet {
+    const builder = new RangeSetBuilder<Decoration>();
+
+    for (const { from, to } of view.visibleRanges) {
+      const doc = view.state.doc;
+      const startLine = doc.lineAt(from).number;
+      const endLine = doc.lineAt(to).number;
+
+      for (let index = startLine; index <= endLine; index++) {
+        const line = doc.line(index);
+        const words = line.text.trim().split(/\s+/).filter((w) => w.length > 0);
+
+        if (words.length > 0) {
+          builder.add(
+            line.to,
+            line.to,
+            Decoration.widget({
+              side: 1,
+              widget: new SampleWidget(words.length)
+            })
+          );
+        }
+      }
+    }
+
+    return builder.finish();
+  }
+}
+
+const pluginSpec: PluginSpec<SampleViewPlugin> = {
+  decorations: (value: SampleViewPlugin) => value.decorations
+};
+
+export const sampleViewPlugin = ViewPlugin.fromClass(
+  SampleViewPlugin,
+  pluginSpec
+);

package/templates/default/src/editor-extensions/sample-widget.ts.ejs

@@ -0,0 +1,22 @@
+import { WidgetType } from '@codemirror/view';
+
+export class SampleWidget extends WidgetType {
+  private readonly count: number;
+
+  public constructor(count: number) {
+    super();
+    this.count = count;
+  }
+
+  public override eq(other: SampleWidget): boolean {
+    return this.count === other.count;
+  }
+
+  public toDOM(): HTMLElement {
+    const span = createSpan({
+      cls: 'cm-sample-word-count',
+      text: ` [${String(this.count)} words]`
+    });
+    return span;
+  }
+}