dsh-plugin-toolkit 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.0
+
+- `dsh-plugin-toolkit/testkit`: mount a single-file client bundle in jsdom with the real React and a recording host context — `click`, `type`, `press`, `must`, `attributes`, and normalised DOM baselines.
+- `createFetch(routes)`: route stubs for the panel's own endpoints, with a request log; an undeclared route answers 404 rather than hanging.
+- `dsh-plugin mount <client.js>`: render a bundle in Node and print the text a user would see, or the markup with `--html`.
+- The host merges locale registrations per namespace and understands both a flat table and a `{en, zh}` language map, which is what real plugins register.
+
 ## 0.1.1
 
 - Ship a composite GitHub Action (`action.yml`), so a plugin repository can run the same checks with `uses: WJDdidi-1/dsh-plugin-toolkit@v1`.

package/README.md

@@ -23,6 +23,48 @@ Releasing one plugin fifteen times taught me three things the ecosystem's toolin
 3. **Reading a manifest is not the same as checking it.** A plugin can have a valid `package.json` and still be uninstallable: `files` that omit the entry the manifest points at, a bundle patch that does not exist, a README that never states the host range it declares.
 
 
+## Test a panel without a browser
+
+A plugin's client code is one file that calls `window.__ModuleLoader__.load({factory})` — there is no module to import, so the usual React test setup does not apply. `testkit` supplies the missing half: a DOM, the real React, and a host context that records what the panel registers.
+
+```sh
+npm install --save-dev jsdom react react-dom
+```
+
+```js
+import { mountClient, createFetch } from 'dsh-plugin-toolkit/testkit';
+
+const panel = await mountClient({
+  file: 'client.js',
+  copy: { 'my-plugin': { title: 'My panel' } },
+  fetch: createFetch({
+    '/my-plugin/report': { body: { score: 71, noise: 3 } },
+    '/my-plugin/apply': () => ({ status: 201, body: { score: 92 } }),
+  }),
+});
+
+await panel.click('[data-testid="optimize"]');
+console.assert(panel.text().includes('92'), 'the score on screen did not move');
+console.assert(panel.must('[role="status"]').textContent.includes('92'));
+await panel.unmount();
+```
+
+What you get back: `text()`, `html()`, `query(selector)`, `must(selector)` (throws with the rendered HTML when it misses), `click(selector)`, `type(selector, value)`, `press(selector, key)`, `focus`, `attributes(selector)`, `snapshot(dir, name)` for a normalised DOM baseline, and `host` for assertions about what the bundle registered.
+
+To look at a bundle by hand:
+
+```sh
+npx dsh-plugin mount ./client.js            # print the text a user would see
+npx dsh-plugin mount ./client.js --html     # print the markup
+```
+
+That is how the AIignore panel was checked before release: the real bundle, mounted in Node, against a stubbed `/aiignore/*`:
+
+```
+$ npx dsh-plugin mount ../ai-context-doctor/plugin/client.js
+AIignore No workspace yet Could not read the report …
+```
+
 ## Use it in CI
 
 The same checks run as a GitHub Action, so a tag cannot go out on a plugin that would not install:
@@ -81,8 +123,7 @@ npm test
 
 ## Roadmap
 
-- `testkit`: load a single-file client bundle in a DOM with a fake host ctx, so panel behaviour can be asserted in CI instead of by hand.
-- `dev`: watch a client bundle and push it to a running app, instead of restarting the app for every change.
+- `dev`: watch a client bundle and push it to a running app, instead of restarting the app for every change. Needs one probe first: whether the host exposes a channel that accepts a pushed bundle.
 
 ## License
 

package/lib/cli.mjs

@@ -14,6 +14,7 @@ export const HELP = `dsh-plugin — preflight and release DeepSeek Harness plugi
   dsh-plugin doctor [dir]            check the manifest, README and bundle
   dsh-plugin release [dir] [flags]   tag, wait for npm, update the market index
   dsh-plugin index [dir]             audit every version in market/index.json
+  dsh-plugin mount <client.js>       render a client bundle in Node and print what a user would see
 
 Flags
   --dry-run                 show the steps without touching anything
@@ -30,6 +31,9 @@ function flags(argv) {
     else if (token === '--index') parsed.index = argv[++index];
     else if (token === '--tag-prefix') parsed.tagPrefix = argv[++index];
     else if (token === '--budget') parsed.budget = Number(argv[++index]);
+    else if (token === '--slot') parsed.slot = argv[++index];
+    else if (token === '--surface') parsed.surface = argv[++index];
+    else if (token === '--html') parsed.html = true;
     else if (token.startsWith('--') === true) throw new Error(`unknown flag ${token}`);
     else parsed.positional.push(token);
   }
@@ -82,6 +86,24 @@ export async function run(argv, io = console) {
     return problems === 0 ? 0 : 1;
   }
 
+  if (command === 'mount') {
+    const file = options.positional[0];
+    if (file === undefined) {
+      io.error('dsh-plugin mount: name the client bundle to render');
+      return 2;
+    }
+    const { mountClient } = await import('./testkit/index.mjs');
+    const panel = await mountClient({
+      file: path.resolve(file),
+      slot: options.slot ?? 'sidebar.right.pane.tab',
+      surface: options.surface ?? 'sidebar',
+    });
+    io.log(panel.text());
+    if (options.html === true) io.log(panel.html());
+    await panel.unmount();
+    return 0;
+  }
+
   if (command === 'release') {
     const report = doctor(dir);
     const name = report.manifest?.name ?? '(no name)';

package/lib/testkit/env.mjs

@@ -0,0 +1,59 @@
+/**
+ * A DOM for a plugin bundle that was written for a DOM.
+ *
+ * The bundle is one file that runs in the renderer: it calls
+ * `window.__ModuleLoader__.load({factory})` and expects React to already exist.
+ * jsdom plus the real React gives us the same arrangement in Node, which is what
+ * makes panel behaviour assertable in CI instead of by hand.
+ */
+let JSDOM;
+let VirtualConsole;
+try {
+  ({ JSDOM, VirtualConsole } = await import('jsdom'));
+} catch {
+  throw new Error('testkit needs a DOM: npm install --save-dev jsdom react react-dom');
+}
+
+export function createDom({ html = '<!doctype html><html><body><div id="root"></div></body></html>' } = {}) {
+  // jsdom's CSS parser predates nesting and `:has()`, so it complains about
+  // stylesheets it cannot parse. That is a jsdom limit, not a panel bug.
+  const virtualConsole = new VirtualConsole();
+  virtualConsole.on('jsdomError', (error) => {
+    if (/Could not parse CSS stylesheet/.test(error.message) === true) return;
+    console.error(error.message);
+  });
+  const dom = new JSDOM(html, { url: 'http://localhost/', pretendToBeVisual: true, virtualConsole });
+  return { dom, window: dom.window, document: dom.window.document };
+}
+
+/**
+ * Installs the globals a renderer-side bundle reaches for. `previous` is
+ * returned so a test file can put the process back the way it found it.
+ */
+export function installGlobals(window, document) {
+  const names = ['window', 'document', 'navigator', 'HTMLElement', 'Element', 'Node', 'Event', 'CustomEvent', 'MouseEvent', 'KeyboardEvent', 'getComputedStyle', 'requestAnimationFrame', 'cancelAnimationFrame'];
+  const previous = new Map();
+  const define = (name, value) => {
+    const descriptor = Object.getOwnPropertyDescriptor(globalThis, name);
+    previous.set(name, descriptor);
+    // Node 24 ships `navigator` as a getter; assigning to it throws, so the
+    // global is replaced with defineProperty and put back the same way.
+    Object.defineProperty(globalThis, name, { value, configurable: true, writable: true, enumerable: descriptor?.enumerable ?? true });
+  };
+  for (const name of names) {
+    const value = name === 'window' ? window : window[name];
+    if (value === undefined) continue;
+    define(name, value);
+  }
+  define('self', window);
+  // React 19 only runs effects through act() when it is told it is in a test.
+  const previousAct = Object.getOwnPropertyDescriptor(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+  previous.set('IS_REACT_ACT_ENVIRONMENT', previousAct);
+  Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', { value: true, configurable: true, writable: true });
+  return () => {
+    for (const [name, descriptor] of previous) {
+      if (descriptor === undefined) delete globalThis[name];
+      else Object.defineProperty(globalThis, name, descriptor);
+    }
+  };
+}

package/lib/testkit/fetch.mjs

@@ -0,0 +1,40 @@
+/**
+ * Route stubs for the plugin's own endpoints.
+ *
+ * The panel talks to itself over HTTP (`/aiignore/report` and friends), so a
+ * test states what each route answers and gets a log of what was asked. A route
+ * that is not declared answers 404 on purpose: silence hides missing calls.
+ */
+export function createFetch(routes = {}) {
+  const requests = [];
+  const answer = (pathname, search) => {
+    const key = Object.keys(routes).find((route) => route === pathname || route === `${pathname}${search}`);
+    if (key === undefined) return null;
+    const value = routes[key];
+    const resolved = typeof value === 'function' ? value({ pathname, search, requests }) : value;
+    const status = resolved?.status ?? 200;
+    const body = resolved?.body ?? resolved ?? {};
+    return {
+      ok: status >= 200 && status < 300,
+      status,
+      headers: { get: (name) => (String(name).toLowerCase() === 'content-type' ? 'application/json' : null) },
+      json: async () => body,
+      text: async () => JSON.stringify(body),
+    };
+  };
+
+  const fetchStub = async (input, init = {}) => {
+    const raw = typeof input === 'string' ? input : input?.url ?? String(input);
+    const url = new URL(raw, 'http://localhost/');
+    const method = (init.method ?? 'GET').toUpperCase();
+    const entry = { method, path: url.pathname, search: url.search, body: init.body ?? null };
+    requests.push(entry);
+    const found = answer(url.pathname, url.search);
+    if (found !== null) return found;
+    return { ok: false, status: 404, headers: { get: () => null }, json: async () => ({}), text: async () => '' };
+  };
+
+  fetchStub.requests = requests;
+  fetchStub.calls = (pathname) => requests.filter((request) => request.path === pathname);
+  return fetchStub;
+}

package/lib/testkit/host.mjs

@@ -0,0 +1,126 @@
+/**
+ * The smallest host that a panel can be honest against.
+ *
+ * A plugin registers slots, a locale table and a sidebar tab; this records what
+ * it registered and calls the callbacks the way the host would. Nothing here
+ * pretends to be more than the surface the panel actually uses — if a panel
+ * needs something else, the missing service throws with its own name.
+ */
+export function createHost({ locale = {}, fetch: fetchImpl, surface = 'sidebar' } = {}) {
+  const registrations = { slots: [], tabs: [], locales: [], effects: [] };
+  const opened = [];
+  const injected = [];
+
+  const slots = {
+    register(definition, component) {
+      registrations.slots.push({ definition, component });
+      return () => {};
+    },
+    inject(name, run) {
+      const result = run();
+      if (typeof result === 'function') return result;
+      return () => {};
+    },
+  };
+
+  const localeService = {
+    register(namespace, dictionary) {
+      // Two shapes reach this: a flat key → text table, and a language map
+      // ({en: {...}, zh: {...}}). Both are legal, so both are kept.
+      const entry = { namespace, dictionary: {}, languages: null };
+      const values = Object.values(dictionary ?? {});
+      const isLanguageMap = values.length > 0 && values.every((value) => value !== null && typeof value === 'object' && Array.isArray(value) === false);
+      if (isLanguageMap === true) entry.languages = { ...dictionary };
+      else Object.assign(entry.dictionary, dictionary);
+      const existing = registrations.locales.findIndex((item) => item.namespace === namespace);
+      if (existing === -1) registrations.locales.push(entry);
+      else {
+        const previous = registrations.locales[existing];
+        Object.assign(previous.dictionary, entry.dictionary);
+        if (entry.languages !== null) previous.languages = { ...(previous.languages ?? {}), ...entry.languages };
+      }
+      return () => {};
+    },
+    bind(namespace, language = 'en') {
+      const entry = registrations.locales.find((item) => item.namespace === namespace);
+      const table = entry?.languages?.[language] ?? entry?.languages?.[Object.keys(entry.languages ?? {})[0]] ?? entry?.dictionary;
+      return (key, values) => {
+        const template = table?.[key];
+        if (typeof template !== 'string') return key;
+        if (values === undefined) return template;
+        return template.replace(/\{(\w+)\}/g, (match, name) => (Object.prototype.hasOwnProperty.call(values, name) ? String(values[name]) : match));
+      };
+    },
+  };
+
+  const sidebarRightTabs = {
+    register(definition) {
+      registrations.tabs.push(definition);
+      return () => {};
+    },
+  };
+
+  const sidebarRight = {
+    openTab(kind) {
+      opened.push(kind);
+      return undefined;
+    },
+    active: () => null,
+    isExpanded: () => true,
+    toggleExpanded() {},
+  };
+
+  const services = {
+    slots,
+    locale: localeService,
+    sidebarRightTabs,
+    sidebarRight,
+    // A relative URL is normal in the renderer and impossible for Node's fetch,
+    // so the default answers "nothing here" instead of throwing a parse error.
+    fetch:
+      fetchImpl ??
+      (async () => ({
+        ok: false,
+        status: 404,
+        headers: { get: () => null },
+        json: async () => ({}),
+        text: async () => '',
+      })),
+    // `ctx.inject(names, cb)` is how a plugin asks for services lazily.
+    inject(names, callback) {
+      injected.push(names);
+      // The real host hands back a ctx that can still resolve other services;
+      // a plugin that checks `tabCtx.slots` before registering must see it.
+      const subset = Object.assign({}, services);
+      for (const name of names) subset[name] = services[name];
+      return callback(subset);
+    },
+    effect(run) {
+      registrations.effects.push(run);
+      const dispose = run();
+      return () => {
+        if (typeof dispose === 'function') dispose();
+      };
+    },
+    on() {
+      return () => {};
+    },
+    logger: { info() {}, warn() {}, error() {}, debug() {} },
+    console,
+  };
+
+  if (surface === 'overlay') {
+    delete services.sidebarRightTabs;
+    delete services.sidebarRight;
+  }
+
+  services.registrations = registrations;
+  services.opened = opened;
+  services.injected = injected;
+  services.registeredLocale = (namespace) => registrations.locales.find((item) => item.namespace === namespace)?.dictionary ?? {};
+  services.slot = (name) =>
+    registrations.slots.find(({ definition }) => definition.name === name) ??
+    null;
+  services.tabDefinition = (id) => registrations.tabs.find((definition) => definition.id === id) ?? null;
+  return services;
+}

package/lib/testkit/index.mjs

@@ -0,0 +1,12 @@
+/**
+ * `dsh-plugin-toolkit/testkit` — the public surface.
+ *
+ * A plugin's own test file should be able to say: mount my bundle, click the
+ * button, expect this text — without inventing a DOM, a host, or a renderer.
+ */
+export { createDom, installGlobals } from './env.mjs';
+export { createHost } from './host.mjs';
+export { createFetch } from './fetch.mjs';
+export { createModuleLoader, loadBundle } from './load.mjs';
+export { mountClient } from './mount.mjs';
+export { compare, normalize, snapshotPath, write } from './snapshot.mjs';

package/lib/testkit/load.mjs

@@ -0,0 +1,42 @@
+/**
+ * Loading a client bundle without a bundler.
+ *
+ * DSH ships plugin client code as a single file that registers itself with
+ * `window.__ModuleLoader__.load({id, factory})`. There is no ESM boundary to
+ * import, so the loader is replaced with one that hands the factory a `require`
+ * for the modules the host provides.
+ */
+import fs from 'node:fs';
+
+export function createModuleLoader({ require: provide, onLoad } = {}) {
+  const loaded = [];
+  const loader = {
+    load({ id, factory }) {
+      const module = { exports: {} };
+      const result = factory(provide ?? (() => ({})));
+      const exported = result ?? module.exports;
+      loaded.push({ id, exports: exported });
+      if (typeof onLoad === 'function') onLoad({ id, exports: exported });
+      return exported;
+    },
+    get loaded() {
+      return loaded;
+    },
+  };
+  return loader;
+}
+
+export function loadBundle(file, options = {}) {
+  const source = fs.readFileSync(file, 'utf8');
+  const loader = createModuleLoader(options);
+  const context = { window: { __ModuleLoader__: loader }, __ModuleLoader__: loader, ...(options.globals ?? {}) };
+  // The bundle is an IIFE or a top-level statement list; the browser would run it
+  // as a classic script, so a function body is the closest equivalent.
+  const run = new Function('window', '__ModuleLoader__', 'require', 'module', 'exports', source);
+  const module = { exports: {} };
+  run(context.window, loader, options.require ?? (() => ({})), module, module.exports);
+  if (loader.loaded.length === 0) {
+    throw new Error(`${file} never called window.__ModuleLoader__.load(), so it is not a client bundle`);
+  }
+  return loader.loaded[loader.loaded.length - 1].exports;
+}

package/lib/testkit/mount.mjs

@@ -0,0 +1,184 @@
+/**
+ * Mounting a panel the way the host does, then poking at it the way a user does.
+ *
+ * The helpers are deliberately blunt — click, type, press — because that is the
+ * vocabulary a bug report uses. Anything cleverer hides which selector was hit.
+ */
+import { createDom, installGlobals } from './env.mjs';
+import { createHost } from './host.mjs';
+import { loadBundle } from './load.mjs';
+import { compare, write } from './snapshot.mjs';
+
+function moduleShim(modules) {
+  return (name) => {
+    if (Object.prototype.hasOwnProperty.call(modules, name)) return modules[name];
+    // An unknown host module should be obviously fake, not silently empty.
+    return new Proxy(
+      {},
+      {
+        get: (target, key) => {
+          if (key === 'then') return undefined;
+          if (key === Symbol.toPrimitive) return () => `[unknown module ${name}]`;
+          return () => null;
+        },
+      },
+    );
+  };
+}
+
+export async function mountClient(options) {
+  const {
+    file,
+    copy = {},
+    surface = 'sidebar',
+    slot = 'sidebar.right.pane.tab',
+    props = {},
+    fetch: fetchImpl,
+    container = 'root',
+  } = options;
+
+  const { window, document } = createDom();
+  const restoreGlobals = installGlobals(window, document);
+
+  const React = await import('react');
+  const reactDom = await import('react-dom/client');
+  const jsxRuntime = await import('react/jsx-runtime');
+  const jsxDevRuntime = await import('react/jsx-dev-runtime').catch(() => jsxRuntime);
+
+  const modules = {
+    react: React.default ?? React,
+    'react-dom': await import('react-dom'),
+    'react-dom/client': reactDom.default ?? reactDom,
+    'react/jsx-runtime': jsxRuntime,
+    'react/jsx-dev-runtime': jsxDevRuntime,
+  };
+
+  const host = createHost({ locale: copy, fetch: fetchImpl, surface });
+  // The panel calls the browser's fetch, not a service, so the stub has to be
+  // the global one for the duration of the mount.
+  const previousFetch = globalThis.fetch;
+  globalThis.fetch = host.fetch;
+  try {
+    const exported = loadBundle(file, { require: moduleShim(modules) });
+    const apply = exported.apply ?? exported.default ?? exported.install ?? exported;
+    if (typeof apply !== 'function') {
+      throw new Error(`${file} exports no apply(ctx) function, so there is nothing to mount`);
+    }
+    await apply(host);
+  } catch (error) {
+    globalThis.fetch = previousFetch;
+    restoreGlobals();
+    throw error;
+  }
+
+  const registered = host.slot(slot);
+  if (registered === null) {
+    globalThis.fetch = previousFetch;
+    restoreGlobals();
+    throw new Error(`the bundle registered no "${slot}" slot; it registered: ${[...new Set(host.registrations.slots.map((entry) => entry.definition.name))].join(', ') || 'nothing'}`);
+  }
+
+  const root = document.getElementById(container);
+  const clientRoot = (reactDom.default ?? reactDom).createRoot(root);
+  const act = React.act ?? ((run) => run());
+
+  await act(async () => {
+    clientRoot.render(React.createElement(registered.component, props));
+  });
+
+  const settle = async (run) => {
+    await act(async () => {
+      if (run !== undefined) await run();
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+  };
+
+  const query = (selector) => root.querySelector(selector);
+  const queryAll = (selector) => [...root.querySelectorAll(selector)];
+  const must = (selector) => {
+    const element = query(selector);
+    if (element === null) throw new Error(`no element matched "${selector}" in:\n${root.innerHTML.slice(0, 600)}`);
+    return element;
+  };
+
+  const helpers = {
+    window,
+    document,
+    root,
+    host,
+    react: React,
+    // textContent glues siblings together ("Demo panelCount 0"); a reader of the
+    // screen does not, so leaves are joined with a space.
+    text: () => {
+      const leaves = [];
+      const walk = (node) => {
+        if (node.nodeType === 3) {
+          const value = node.nodeValue.replace(/\s+/g, ' ').trim();
+          if (value !== '') leaves.push(value);
+          return;
+        }
+        if (node.nodeType !== 1) return;
+        const tag = node.tagName.toLowerCase();
+        if (tag === 'script' || tag === 'style') return;
+        for (const child of node.childNodes) walk(child);
+      };
+      walk(root);
+      return leaves.join(' ');
+    },
+    html: () => root.innerHTML,
+    query,
+    queryAll,
+    must,
+    click: async (selector) => {
+      const element = must(selector);
+      await settle(() => {
+        element.dispatchEvent(new window.MouseEvent('click', { bubbles: true, cancelable: true }));
+      });
+      return element;
+    },
+    press: async (selector, key, init = {}) => {
+      const element = selector === null ? root : must(selector);
+      await settle(() => {
+        element.dispatchEvent(new window.KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...init }));
+      });
+      return element;
+    },
+    type: async (selector, value) => {
+      const element = must(selector);
+      const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')?.set
+        ?? Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value')?.set;
+      await settle(() => {
+        setter?.call(element, value);
+        element.dispatchEvent(new window.Event('input', { bubbles: true }));
+      });
+      return element;
+    },
+    focus: (selector) => {
+      const element = must(selector);
+      element.focus();
+      return element;
+    },
+    attributes: (selector) => {
+      const element = must(selector);
+      return Object.fromEntries([...element.attributes].map((attribute) => [attribute.name, attribute.value]));
+    },
+    snapshot: (dir, name) => {
+      const result = compare(dir, name, root.innerHTML);
+      if (result.status === 'changed') {
+        throw new Error(`${name} changed at <${result.actual.split(/(?=<)/)[result.firstDifference]}>`);
+      }
+      if (result.status === 'missing') {
+        throw new Error(`${name} has no baseline at ${result.file}; run with --update to create it`);
+      }
+      return result;
+    },
+    writeSnapshot: (dir, name) => write(dir, name, root.innerHTML),
+    unmount: async () => {
+      await act(async () => clientRoot.unmount());
+      globalThis.fetch = previousFetch;
+      restoreGlobals();
+    },
+  };
+
+  return helpers;
+}

package/lib/testkit/snapshot.mjs

@@ -0,0 +1,47 @@
+/**
+ * DOM snapshots, not pixels.
+ *
+ * A rasterised baseline needs a browser; the DOM does not. Normalising the
+ * markup (class order, whitespace, generated ids) gives a baseline that fails
+ * for the same reasons a screenshot would — a missing class, a lost label, a
+ * control that stopped rendering — and can be reviewed in a diff.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const NOISE = /\s+/g;
+
+export function normalize(html) {
+  return html
+    .replace(/<!--.*?-->/g, '')
+    .replace(/ data-react[a-z-]*="[^"]*"/g, '')
+    .replace(/ aria-describedby="[^"]*"/g, '')
+    .replace(/\s+class="([^"]*)"/g, (match, value) => ` class="${value.split(NOISE).filter(Boolean).sort().join(' ')}"`)
+    .replace(/>\s+</g, '><')
+    .replace(NOISE, ' ')
+    .trim();
+}
+
+export function snapshotPath(dir, name) {
+  return path.join(dir, `${name}.html`);
+}
+
+/** Compares, and on mismatch says which line moved instead of dumping two walls. */
+export function compare(dir, name, html) {
+  const file = snapshotPath(dir, name);
+  const actual = normalize(html);
+  if (fs.existsSync(file) === false) return { file, status: 'missing', actual };
+  const expected = fs.readFileSync(file, 'utf8').trim();
+  if (expected === actual) return { file, status: 'same', actual };
+  const expectedLines = expected.split(/(?=<)/);
+  const actualLines = actual.split(/(?=<)/);
+  const index = expectedLines.findIndex((line, position) => line !== actualLines[position]);
+  return { file, status: 'changed', expected, actual, firstDifference: Math.max(0, index) };
+}
+
+export function write(dir, name, html) {
+  const file = snapshotPath(dir, name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(file, `${normalize(html)}\n`);
+  return file;
+}

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "dsh-plugin-toolkit",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Preflight, release and test DeepSeek Harness plugins: checks what the host needs, waits for npm to actually serve the version, and keeps the market index honest.",
   "type": "module",
   "bin": {
     "dsh-plugin": "bin/dsh-plugin.mjs"
   },
+  "exports": {
+    ".": "./lib/cli.mjs",
+    "./testkit": "./lib/testkit/index.mjs"
+  },
   "files": [
     "bin/",
     "lib/",
@@ -38,6 +42,28 @@
   },
   "scripts": {
     "test": "node --test",
-    "lint": "node --check bin/dsh-plugin.mjs"
+    "lint": "node --check bin/dsh-plugin.mjs",
+    "snapshots": "UPDATE_SNAPSHOTS=1 node --test test/testkit.test.mjs"
+  },
+  "peerDependencies": {
+    "jsdom": ">=26",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "jsdom": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "jsdom": "^26.1.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
   }
 }