@zync-sh/plugin-sdk 2.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zync.sh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# Zync plugin SDK (beta)
+
+Public authoring types for Manifest v2 plugins. This package lives in the Zync repository but has its own npm version and release lifecycle.
+
+Install the prerelease as a development dependency:
+
+```sh
+npm install --save-dev @zync-sh/plugin-sdk@beta
+```
+
+To try the local package from another project, install it by path:
+
+```sh
+npm install --save-dev /path/to/zync/packages/plugin-sdk
+```
+
+Zync supplies the `zync` object when it starts a plugin worker or pane. Do not bundle an SDK runtime into the plugin.
+
+## Manifest
+
+`defineManifest` gives TypeScript a Manifest v2 contract and returns the same object. It does **not** validate a package or grant permissions; the Zync host is the final authority.
+
+```ts
+import { defineManifest } from '@zync-sh/plugin-sdk';
+
+export default defineManifest({
+  manifestVersion: 2,
+  id: 'com.example.hello',
+  name: 'Hello',
+  version: '1.0.0',
+  publisher: 'com.example',
+  engines: { zync: '>=2.32.2', pluginApi: '^2.0.0' },
+  runtime: { entry: 'worker.js' },
+  contributes: {
+    commands: [{ id: 'hello.say-hi', title: 'Say hi' }],
+  },
+  permissions: {
+    required: [{ id: 'ui.commands.register', reason: 'Add the command to Zync.' }],
+  },
+});
+```
+
+Write the resulting object to `manifest.json` during your build. Zync installs the JSON and the built plugin files, not the TypeScript source.
+
+## Validate before signing
+
+Run the packaged CLI against the **built plugin directory** (the one containing `manifest.json` and its referenced assets):
+
+```sh
+npx zync-plugin validate ./dist/my-plugin --zync-version 2.32.2
+```
+
+In this repository, the same check is available as `npm run plugin:validate -- ./examples/plugins/manifest-v2-demo`. For programmatic checks, import `validateManifest` or `validatePackageDirectory` from `@zync-sh/plugin-sdk/validate`. Validation returns `{ valid, issues }`; warnings do not fail the check.
+
+The preflight checks Manifest v2 fields, publisher namespace, semantic plugin version, contribution/permission declarations, known permissions, network host declarations, referenced files, basic package limits, and plugin API compatibility. Pass `--zync-version` to check compatibility with a specific app build; without it, the Zync range is syntax-checked only. Unknown optional permissions produce warnings because the host denies them until supported. The preflight does **not** validate signatures, inspect executable behavior, or replace native install-time validation. The signing tool and native host retain their own package and security checks.
+
+The [basic starter template](templates/basic/README.md) is included in this package. It builds a minimal worker and isolated pane, then validates the output. See [RELEASE.md](RELEASE.md) for versioning and the publication checklist.
+
+## Host-provided APIs
+
+For a worker:
+
+```ts
+import type { ZyncWorkerApi } from '@zync-sh/plugin-sdk/worker';
+
+declare const zync: ZyncWorkerApi;
+
+zync.on('ready', async () => {
+  await zync.commands.register('hello.say-hi', 'Say hi', async () => {
+    await zync.ui.notify({ message: 'Hello from the plugin' });
+  });
+});
+```
+
+For an isolated pane, use `import type { ZyncPaneApi } from '@zync-sh/plugin-sdk/pane'` and declare `window.zync` with that type in your pane source. Panes can exchange messages with their worker; they do not get the worker API, host DOM, or direct network access.
+
+The typed worker interface covers the Manifest v2 broker APIs only. Legacy plugin APIs are deliberately absent. Every host operation is still checked against the installed manifest, current grant, runtime identity, and applicable scope. The SDK version does not replace the manifest's `engines.pluginApi` compatibility declaration.
+
+See the [plugin architecture](https://github.com/zync-sh/zync/blob/main/docs/PLUGINS.md) and [Manifest v2 demo](https://github.com/zync-sh/zync/tree/main/examples/plugins/manifest-v2-demo) for package format, permissions, signing, and manual testing.

package/RELEASE.md

@@ -0,0 +1,16 @@
+# SDK release policy
+
+The npm package version and the Zync plugin API version are separate. `@zync-sh/plugin-sdk` may release documentation, types, or tooling fixes without changing the host API. A breaking host API requires a new `engines.pluginApi` major version and matching native/SDK support. Plugin packages continue to declare their own `version`, `engines.zync`, and `engines.pluginApi` ranges.
+
+Manifest v2 engine ranges use semantic-version comparators such as `^2.0.0`, `>=2.32.2`, or `>=2.32.2, <3.0.0`. Avoid npm-only unions (`||`) and hyphen ranges; the native host is authoritative. Pre-release host versions require a matching pre-release comparator. When a plugin's engine range does not match the running host, Zync rejects install/activation or skips loading the installed plugin. A rollback to an incompatible retained version is rejected before replacing the active package.
+
+Before a beta npm SDK release:
+
+1. Run `npm run sdk:release-check` from the Zync repository root. It checks type contracts, validator cases, the starter build, and the exact npm package contents.
+2. Run the native plugin tests and the full agent regression suite.
+3. Run `node check.mjs` in the sibling `zync-plugin-channel-examples` project to validate, sign, and verify stable and beta builds in a disposable registry.
+4. Review the exact SDK tarball, production dependency audit, license, and documentation. Publish the prerelease with the `beta` npm tag, never `latest`, and install it in a clean project to verify the CLI and exported types.
+
+The SDK beta is an authoring tool, not a production marketplace launch. Before promoting it to `latest` or calling the marketplace production-ready, deploy the signed test builds to a protected HTTPS staging registry. Manually verify marketplace listing, opt-in beta update, switch back to stable, permission review, and retained-version rollback in the desktop app. Record the tested Zync build, SDK version, registry version, and package digests; complete the external-plugin smoke test and independent security review. Local signing tests do not substitute for these checks.
+
+The automatic checks are not a security audit. Do not publish the package merely because they pass.

package/bin/zync-plugin.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { validatePackageDirectory } from '../validate.js';
+
+const [command, directory, ...extra] = process.argv.slice(2);
+const withVersion = extra.length === 2 && extra[0] === '--zync-version';
+if (command !== 'validate' || !directory || (extra.length && !withVersion)) {
+  console.error('Usage: zync-plugin validate <plugin-directory> [--zync-version <version>]');
+  process.exitCode = 2;
+} else {
+  try {
+    const result = validatePackageDirectory(directory, withVersion ? { zyncVersion: extra[1] } : {});
+    for (const issue of result.issues) {
+      const stream = issue.severity === 'error' ? process.stderr : process.stdout;
+      stream.write(`${issue.severity}: ${issue.path}: ${issue.message}\n`);
+    }
+    if (result.valid) console.log('Plugin preflight passed. Zync will validate again at install time.');
+    else process.exitCode = 1;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}

package/index.d.ts

@@ -0,0 +1,42 @@
+export interface PermissionRequest {
+  id: string;
+  reason: string;
+  scope?: string;
+  hosts?: string[];
+}
+
+export interface SurfaceContribution {
+  id: string;
+  title: string;
+  entry: string;
+  allowMultiple?: boolean;
+}
+
+export interface ManifestV2 {
+  manifestVersion: 2;
+  id: string;
+  name: string;
+  version: string;
+  publisher: string;
+  description?: string;
+  license?: string;
+  homepage?: string;
+  support?: string;
+  privacyPolicy?: string;
+  engines: { zync: string; pluginApi: string };
+  runtime?: { entry?: string };
+  contributes?: {
+    commands?: Array<{ id: string; title: string }>;
+    paneKinds?: SurfaceContribution[];
+    dashboardCards?: SurfaceContribution[];
+  };
+  permissions?: {
+    required?: PermissionRequest[];
+    optional?: PermissionRequest[];
+  };
+  icon?: string;
+  type?: string;
+}
+
+/** Type-checks the manifest; the native host remains the final validator. */
+export function defineManifest<T extends ManifestV2>(manifest: T): T;

package/index.js

@@ -0,0 +1,4 @@
+/** Returns a Manifest v2 object without changing it. Zync validates the package at install time. */
+export function defineManifest(manifest) {
+  return manifest;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@zync-sh/plugin-sdk",
+  "version": "2.0.0-beta.1",
+  "description": "Manifest v2 authoring types and preflight validation for Zync plugins",
+  "type": "module",
+  "dependencies": { "semver": "^7.0.0" },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zync-sh/zync.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "engines": { "node": ">=20" },
+  "sideEffects": false,
+  "files": ["index.js", "index.d.ts", "worker.d.ts", "pane.d.ts", "validate.js", "validate.d.ts", "bin/zync-plugin.mjs", "templates/basic", "README.md", "RELEASE.md", "LICENSE"],
+  "exports": {
+    ".": { "types": "./index.d.ts", "default": "./index.js" },
+    "./validate": { "types": "./validate.d.ts", "default": "./validate.js" },
+    "./worker": { "types": "./worker.d.ts" },
+    "./pane": { "types": "./pane.d.ts" }
+  },
+  "bin": { "zync-plugin": "bin/zync-plugin.mjs" },
+  "types": "./index.d.ts",
+  "scripts": { "prepublishOnly": "node ../../scripts/plugin-signing/sdk-release-check.mjs" },
+  "publishConfig": { "access": "public" }
+}

package/pane.d.ts

@@ -0,0 +1,6 @@
+export interface ZyncPaneApi {
+  pane: {
+    postMessage(message: unknown): void;
+    onMessage(callback: (message: unknown) => void): () => void;
+  };
+}

package/templates/basic/README.md

@@ -0,0 +1,21 @@
+# Starter Zync plugin
+
+Copy this directory into a new project and replace the sample publisher, id, and name in `manifest.mjs` before distributing it.
+
+Install the prerelease SDK:
+
+```sh
+npm install --save-dev @zync-sh/plugin-sdk@beta
+```
+
+For an unreleased local checkout, install it by path instead:
+
+```sh
+npm install --save-dev /path/to/zync/packages/plugin-sdk
+```
+
+Then run `npm run validate`. That builds `dist/` and checks the manifest, referenced files, permissions, and package limits. You can pass the target app version directly with `npx zync-plugin validate dist --zync-version 2.32.2`.
+
+To test locally, enable Developer Mode in Zync and install the `dist/` folder. Its pane should answer **Ask the Worker**. The pane cannot access the Worker API directly; messages go through Zync's bounded pane channel.
+
+To sign a release, keep your publisher key outside the project and pass the validated `dist/` folder to Zync's signing tool. Do not publish the SDK, source files, keys, or `node_modules` as part of the plugin package.

package/templates/basic/manifest.mjs

@@ -0,0 +1,18 @@
+import { defineManifest } from '@zync-sh/plugin-sdk';
+
+export default defineManifest({
+  manifestVersion: 2,
+  id: 'dev.example.starter',
+  name: 'Starter Pane',
+  version: '1.0.0',
+  publisher: 'dev.example',
+  description: 'A minimal isolated Zync pane.',
+  engines: { zync: '>=2.32.2', pluginApi: '^2.0.0' },
+  runtime: { entry: 'worker.js' },
+  contributes: {
+    paneKinds: [{ id: 'starter.main', title: 'Starter Pane', entry: 'ui/index.html', allowMultiple: true }],
+  },
+  permissions: {
+    required: [{ id: 'ui.pane.register', reason: 'Add the starter pane to the workspace.' }],
+  },
+});

package/templates/basic/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "zync-plugin-starter",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "validate": "npm run build && zync-plugin validate dist"
+  }
+}

package/templates/basic/scripts/build.mjs

@@ -0,0 +1,15 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import manifest from '../manifest.mjs';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const output = path.resolve(process.argv[2] ?? path.join(root, 'dist'));
+if (output === root || !output.startsWith(`${root}${path.sep}`)) {
+  throw new Error('Build output must be a directory inside the plugin project');
+}
+fs.mkdirSync(path.join(output, 'ui'), { recursive: true });
+fs.copyFileSync(path.join(root, 'src', 'worker.js'), path.join(output, 'worker.js'));
+fs.copyFileSync(path.join(root, 'src', 'ui', 'index.html'), path.join(output, 'ui', 'index.html'));
+fs.writeFileSync(path.join(output, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+console.log(`Built plugin: ${output}`);

package/templates/basic/src/ui/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Starter Pane</title></head>
+<body>
+  <h1>Starter Pane</h1>
+  <button id="ping" type="button">Ask the Worker</button>
+  <p id="reply" aria-live="polite">Ready</p>
+  <script>
+    document.getElementById('ping').addEventListener('click', () => {
+      window.zync.pane.postMessage({ type: 'ping' });
+    });
+    window.zync.pane.onMessage(message => {
+      if (message?.type === 'pong') document.getElementById('reply').textContent = message.text;
+    });
+  </script>
+</body>
+</html>

package/templates/basic/src/worker.js

@@ -0,0 +1,11 @@
+// Zync supplies this object in the isolated plugin Worker.
+const zync = globalThis.zync;
+
+zync.on('ready', async () => {
+  await zync.panel.register('starter.main');
+});
+
+zync.panel.onMessage(({ paneInstanceId, message }) => {
+  if (message?.type !== 'ping') return;
+  void zync.panel.postMessage(paneInstanceId, { type: 'pong', text: 'Hello from the Worker' });
+});

package/validate.d.ts

@@ -0,0 +1,24 @@
+export interface ValidationIssue {
+  path: string;
+  message: string;
+  severity: 'error' | 'warning';
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  issues: ValidationIssue[];
+}
+
+export declare const knownPermissionIds: readonly string[];
+export declare const pluginApiVersion: string;
+
+export interface CompatibilityTarget {
+  zyncVersion?: string;
+  pluginApiVersion?: string;
+}
+
+/** Authoring preflight. Native install validation remains authoritative. */
+export function validateManifest(manifest: unknown, target?: CompatibilityTarget): ValidationResult;
+
+/** Checks manifest.json, referenced assets, and basic package limits without modifying the directory. */
+export function validatePackageDirectory(directory: string, target?: CompatibilityTarget): ValidationResult;

package/validate.js

@@ -0,0 +1,327 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { isIP } from 'node:net';
+import semver from 'semver';
+
+// This preflight mirrors author-facing manifest rules. Installation still relies on
+// the native validator, which also enforces package and runtime security boundaries.
+export const knownPermissionIds = Object.freeze([
+  'ui.pane.register', 'ui.dashboard.register', 'ui.commands.register',
+  'ui.status.register', 'ui.notifications.emit', 'ui.sidebar.register',
+  'ui.settings.register', 'editor.provider.register', 'theme.pack.register',
+  'connection.metadata.read', 'terminal.input.send', 'terminal.tab.create',
+  'terminal.command.execute', 'ssh.command.execute',
+  'filesystem.pluginData.read', 'filesystem.pluginData.write',
+  'filesystem.external.read', 'filesystem.external.write', 'ssh.filesystem.read',
+  'network.fetch', 'network.local', 'ui.dialog.confirm', 'clipboard.read',
+  'clipboard.write', 'plugins.metadata.read',
+]);
+
+const knownPermissions = new Set(knownPermissionIds);
+export const pluginApiVersion = '2.0.0';
+const identifierPattern = /^[A-Za-z0-9_.-]+$/;
+const semverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const contributionPermissions = {
+  commands: 'ui.commands.register',
+  paneKinds: 'ui.pane.register',
+  dashboardCards: 'ui.dashboard.register',
+};
+const contributionLimits = { commands: 128, paneKinds: 64, dashboardCards: 64 };
+
+function record(issues, location, message, severity = 'error') {
+  issues.push({ path: location, message, severity });
+}
+
+function object(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function text(issues, value, location, maxLength, required = true) {
+  if (value === undefined && !required) return false;
+  if (typeof value !== 'string' || !value.trim() || [...value].length > maxLength || /[\u0000-\u001f\u007f]/.test(value)) {
+    record(issues, location, `Must be non-empty text of at most ${maxLength} characters without controls`);
+    return false;
+  }
+  return true;
+}
+
+function identifier(issues, value, location) {
+  if (!text(issues, value, location, 128)) return false;
+  if (!identifierPattern.test(value) || value.startsWith('.') || value.endsWith('.') || value.includes('..')) {
+    record(issues, location, 'Must be an identifier using letters, digits, dot, dash, or underscore');
+    return false;
+  }
+  return true;
+}
+
+function assetPath(issues, value, location, required = false) {
+  if (value === undefined && !required) return false;
+  if (!text(issues, value, location, 260)) return false;
+  if (value.startsWith('/') || value.includes('\\') || value.includes(':') || value.split('/').some(part => !part || part === '.' || part === '..')) {
+    record(issues, location, 'Must be a relative path inside the plugin package');
+    return false;
+  }
+  return true;
+}
+
+function httpsUrl(issues, value, location) {
+  if (value === undefined || !text(issues, value, location, 2048)) return;
+  try {
+    const url = new URL(value);
+    if (url.protocol === 'https:' && url.hostname && !url.username && !url.password) return;
+  } catch { /* Report one actionable error below. */ }
+  record(issues, location, 'Must be an HTTPS URL without embedded credentials');
+}
+
+function permissionHost(issues, host, location) {
+  if (typeof host !== 'string' || !host || /[/:@?#\\\s]/.test(host)) {
+    record(issues, location, 'Must be a domain name without a scheme, path, port, or credentials');
+    return;
+  }
+  if (host.includes('*') && !host.startsWith('*.')) {
+    record(issues, location, 'A wildcard may appear only as a leading *.');
+    return;
+  }
+  const domain = host.startsWith('*.') ? host.slice(2) : host;
+  if (!domain || domain.includes('*') || isIP(domain) || domain.split('.').some(part => !part)) {
+    record(issues, location, 'Must be a domain name, not an IP address');
+    return;
+  }
+  try {
+    if (new URL(`https://${domain}`).hostname) return;
+  } catch { /* Report one actionable error below. */ }
+  record(issues, location, 'Must be a valid domain name');
+}
+
+function validatePermissions(issues, value) {
+  if (value === undefined) return new Set();
+  if (!object(value)) {
+    record(issues, 'permissions', 'Must be an object');
+    return new Set();
+  }
+  const declared = new Set();
+  let count = 0;
+  for (const group of ['required', 'optional']) {
+    const entries = value[group] ?? [];
+    if (!Array.isArray(entries)) {
+      record(issues, `permissions.${group}`, 'Must be an array');
+      continue;
+    }
+    count += entries.length;
+    entries.forEach((entry, index) => {
+      const location = `permissions.${group}[${index}]`;
+      if (!object(entry)) {
+        record(issues, location, 'Must be an object');
+        return;
+      }
+      if (identifier(issues, entry.id, `${location}.id`)) {
+        if (declared.has(entry.id)) record(issues, `${location}.id`, 'Permission is declared more than once');
+        declared.add(entry.id);
+        if (!knownPermissions.has(entry.id)) {
+          record(issues, `${location}.id`, group === 'required'
+            ? 'Unknown required permission'
+            : 'Unknown optional permission; Zync will deny it until supported', group === 'required' ? 'error' : 'warning');
+        }
+      }
+      text(issues, entry.reason, `${location}.reason`, 240);
+      text(issues, entry.scope, `${location}.scope`, 80, false);
+      const hosts = entry.hosts ?? [];
+      if (!Array.isArray(hosts)) {
+        record(issues, `${location}.hosts`, 'Must be an array');
+        return;
+      }
+      if (hosts.length > 32) record(issues, `${location}.hosts`, 'May contain at most 32 hosts');
+      if (hosts.length && !['network.fetch', 'network.local'].includes(entry.id)) {
+        record(issues, `${location}.hosts`, 'Only network permissions may declare hosts');
+      }
+      if (entry.id === 'network.fetch' && !hosts.length) {
+        record(issues, `${location}.hosts`, 'network.fetch requires at least one host');
+      }
+      const seen = new Set();
+      hosts.forEach((host, hostIndex) => {
+        permissionHost(issues, host, `${location}.hosts[${hostIndex}]`);
+        if (typeof host === 'string') {
+          const key = host.toLowerCase();
+          if (seen.has(key)) record(issues, `${location}.hosts[${hostIndex}]`, 'Host is declared more than once');
+          seen.add(key);
+        }
+      });
+    });
+  }
+  if (count > 64) record(issues, 'permissions', 'May declare at most 64 permissions');
+  return declared;
+}
+
+function validateContributions(issues, value, declared, assets) {
+  if (value === undefined) return;
+  if (!object(value)) {
+    record(issues, 'contributes', 'Must be an object');
+    return;
+  }
+  for (const key of Object.keys(value)) {
+    if (!(key in contributionLimits)) record(issues, `contributes.${key}`, 'Unknown contribution kind');
+  }
+  for (const [kind, limit] of Object.entries(contributionLimits)) {
+    const entries = value[kind] ?? [];
+    if (!Array.isArray(entries)) {
+      record(issues, `contributes.${kind}`, 'Must be an array');
+      continue;
+    }
+    if (entries.length > limit) record(issues, `contributes.${kind}`, `May contain at most ${limit} entries`);
+    if (entries.length && !declared.has(contributionPermissions[kind])) {
+      record(issues, `contributes.${kind}`, `Requires ${contributionPermissions[kind]} permission`);
+    }
+    const seen = new Set();
+    entries.forEach((entry, index) => {
+      const location = `contributes.${kind}[${index}]`;
+      if (!object(entry)) {
+        record(issues, location, 'Must be an object');
+        return;
+      }
+      if (identifier(issues, entry.id, `${location}.id`)) {
+        if (seen.has(entry.id)) record(issues, `${location}.id`, 'Contribution id is declared more than once');
+        seen.add(entry.id);
+      }
+      text(issues, entry.title, `${location}.title`, 120);
+      if (kind !== 'commands') {
+        if (assetPath(issues, entry.entry, `${location}.entry`, true)) assets.push({ path: entry.entry, location: `${location}.entry` });
+        if (entry.allowMultiple !== undefined && typeof entry.allowMultiple !== 'boolean') {
+          record(issues, `${location}.allowMultiple`, 'Must be a boolean');
+        }
+      }
+    });
+  }
+}
+
+function engineRange(issues, range, location, installedVersion) {
+  if (!text(issues, range, location, 80)) return;
+  // Rust's host-side VersionReq does not support npm's union and hyphen syntax.
+  if (range.includes('||') || /\s-\s/.test(range) || !semver.validRange(range)) {
+    record(issues, location, 'Must be a supported semantic version range');
+    return;
+  }
+  if (installedVersion !== undefined) {
+    if (!semver.valid(installedVersion)) {
+      record(issues, location, `Target version is invalid: ${installedVersion}`);
+    } else if (!semver.satisfies(installedVersion, range)) {
+      record(issues, location, `Requires ${range}, but the target provides ${installedVersion}`);
+    }
+  }
+}
+
+export function validateManifest(manifest, options = {}) {
+  const issues = [];
+  const assets = [];
+  if (!object(manifest)) {
+    record(issues, 'manifest', 'Must be a JSON object');
+    return { valid: false, issues, assets };
+  }
+  if (manifest.manifestVersion !== 2) record(issues, 'manifestVersion', 'Must be 2');
+  const validId = identifier(issues, manifest.id, 'id');
+  text(issues, manifest.name, 'name', 80);
+  const versionMatch = text(issues, manifest.version, 'version', 64) && semverPattern.exec(manifest.version);
+  if (versionMatch && versionMatch[4]?.split('.').some(part => /^\d+$/.test(part) && part.length > 1 && part.startsWith('0'))) {
+    record(issues, 'version', 'Numeric prerelease identifiers must not have leading zeroes');
+  } else if (typeof manifest.version === 'string' && !versionMatch) {
+    record(issues, 'version', 'Must be a semantic version such as 1.0.0 or 1.0.0-beta.1');
+  }
+  const validPublisher = identifier(issues, manifest.publisher, 'publisher');
+  if (validId && validPublisher && !manifest.id.startsWith(`${manifest.publisher}.`)) {
+    record(issues, 'id', 'Must be namespaced to the publisher');
+  }
+  if (!object(manifest.engines)) {
+    record(issues, 'engines', 'Must declare zync and pluginApi version ranges');
+  } else {
+    engineRange(issues, manifest.engines.zync, 'engines.zync', options.zyncVersion);
+    engineRange(issues, manifest.engines.pluginApi, 'engines.pluginApi', options.pluginApiVersion ?? pluginApiVersion);
+  }
+  text(issues, manifest.description, 'description', 500, false);
+  text(issues, manifest.license, 'license', 80, false);
+  for (const field of ['homepage', 'support', 'privacyPolicy']) httpsUrl(issues, manifest[field], field);
+  if (manifest.runtime !== undefined && !object(manifest.runtime)) {
+    record(issues, 'runtime', 'Must be an object');
+  } else if (manifest.runtime && assetPath(issues, manifest.runtime.entry, 'runtime.entry')) {
+    assets.push({ path: manifest.runtime.entry, location: 'runtime.entry' });
+  }
+  for (const field of ['main', 'style', 'icon']) {
+    if (assetPath(issues, manifest[field], field)) assets.push({ path: manifest[field], location: field });
+  }
+  const declared = validatePermissions(issues, manifest.permissions);
+  validateContributions(issues, manifest.contributes, declared, assets);
+  return { valid: !issues.some(issue => issue.severity === 'error'), issues, assets };
+}
+
+export function validatePackageDirectory(directory, options = {}) {
+  const root = path.resolve(directory);
+  const issues = [];
+  let rootStat;
+  try { rootStat = fs.lstatSync(root); } catch { /* Report below. */ }
+  if (!rootStat?.isDirectory() || rootStat.isSymbolicLink()) {
+    record(issues, 'package', 'Must be an existing directory, not a link');
+    return { valid: false, issues };
+  }
+  const manifestPath = path.join(root, 'manifest.json');
+  let manifestStat;
+  try { manifestStat = fs.lstatSync(manifestPath); } catch { /* Report below. */ }
+  if (!manifestStat?.isFile() || manifestStat.isSymbolicLink()) {
+    record(issues, 'manifest.json', 'Must be a regular file');
+    return { valid: false, issues };
+  }
+  if (manifestStat.size > 256 * 1024) {
+    record(issues, 'manifest.json', 'Exceeds the native 256 KiB manifest limit');
+    return { valid: false, issues };
+  }
+  let manifest;
+  try { manifest = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(manifestPath))); }
+  catch (error) {
+    record(issues, 'manifest.json', `Invalid JSON: ${error.message}`);
+    return { valid: false, issues };
+  }
+  const result = validateManifest(manifest, options);
+  issues.push(...result.issues);
+  for (const asset of result.assets) {
+    let current = root;
+    let valid = true;
+    for (const segment of asset.path.split('/')) {
+      current = path.join(current, segment);
+      let stat;
+      try { stat = fs.lstatSync(current); } catch { /* Report below. */ }
+      if (!stat || stat.isSymbolicLink()) {
+        record(issues, asset.location, `Referenced file is missing or linked: ${asset.path}`);
+        valid = false;
+        break;
+      }
+    }
+    if (valid && !fs.lstatSync(current).isFile()) record(issues, asset.location, `Referenced path is not a file: ${asset.path}`);
+  }
+  const pending = [root];
+  let entries = 0;
+  let totalBytes = 0;
+  while (pending.length) {
+    const parent = pending.pop();
+    for (const entry of fs.readdirSync(parent, { withFileTypes: true })) {
+      const absolute = path.join(parent, entry.name);
+      const relative = path.relative(root, absolute).split(path.sep).join('/');
+      const stat = fs.lstatSync(absolute);
+      entries += 1;
+      if (entries > 2_048) {
+        record(issues, 'package', 'Contains more than 2,048 entries');
+        pending.length = 0;
+        break;
+      }
+      if (Buffer.byteLength(relative) > 512 || relative.split('/').some(part => part.includes(':') || /[\u0000-\u001f\u007f]/.test(part))) {
+        record(issues, relative, 'Invalid package path');
+      }
+      if (stat.isSymbolicLink() || (!stat.isFile() && !stat.isDirectory())) {
+        record(issues, relative, 'Package entries must be regular files or directories, not links');
+      } else if (stat.isDirectory()) {
+        pending.push(absolute);
+      } else {
+        if (stat.size > 20 * 1024 * 1024) record(issues, relative, 'File exceeds the native 20 MiB limit');
+        totalBytes += stat.size;
+      }
+    }
+  }
+  if (totalBytes > 100 * 1024 * 1024) record(issues, 'package', 'Exceeds the native 100 MiB expanded-size limit');
+  return { valid: !issues.some(issue => issue.severity === 'error'), issues };
+}

package/worker.d.ts

@@ -0,0 +1,72 @@
+export interface PluginFileHandle {
+  handle: string;
+  kind: 'file' | 'directory';
+  access: 'read' | 'write';
+  name: string;
+}
+
+export interface PluginFileEntry {
+  name: string;
+  kind: 'file' | 'directory' | 'unavailable';
+  size?: number;
+}
+
+export interface PluginNetworkResponse {
+  status: number;
+  finalUrl: string;
+  contentType?: string;
+  body: string;
+  bodyEncoding: 'utf8' | 'base64';
+}
+
+export interface PluginNotification {
+  type?: 'info' | 'success' | 'warning' | 'error';
+  title?: string;
+  message?: string;
+  body?: string;
+  duration?: number;
+  persist?: boolean;
+  silent?: boolean;
+  history?: boolean;
+  channel?: 'auto' | 'toast' | 'inbox' | 'both';
+  id?: string;
+  actions?: Array<{ id: string; label: string; dismiss?: boolean }>;
+}
+
+export interface ZyncWorkerApi {
+  on(event: 'ready', callback: () => void | Promise<void>): () => void;
+  ui: {
+    notify(options: PluginNotification): Promise<{ ok: true }>;
+    confirm(options: { title: string; message: string; confirmLabel?: string; cancelLabel?: string }): Promise<boolean>;
+    onNotifyAction(callback: (event: { actionId: string; notificationId?: string }) => void | Promise<unknown>): () => void;
+  };
+  commands: {
+    register(id: string, title: string, handler: () => void | Promise<void>): Promise<{ ok: boolean }>;
+  };
+  panel: {
+    register(id: string): Promise<{ id: string; title: string }>;
+    onMessage(callback: (event: { paneInstanceId: string; message: unknown }) => void): () => void;
+    postMessage(paneInstanceId: string, message: unknown): Promise<boolean>;
+  };
+  storage: {
+    get(key: string): Promise<string | null>;
+    keys(): Promise<string[]>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<boolean>;
+  };
+  network: {
+    fetch(url: string, options?: { accept?: string }): Promise<PluginNetworkResponse>;
+  };
+  filesystem: {
+    pickFile(): Promise<PluginFileHandle | null>;
+    pickDirectory(): Promise<PluginFileHandle | null>;
+    pickWriteFile(): Promise<PluginFileHandle | null>;
+    readText(handle: string, relativePath?: string): Promise<string>;
+    writeText(handle: string, content: string): Promise<void>;
+    list(handle: string, relativePath?: string): Promise<PluginFileEntry[]>;
+  };
+  sshFilesystem: {
+    list(paneInstanceId: string, relativePath?: string): Promise<PluginFileEntry[]>;
+    readText(paneInstanceId: string, relativePath: string): Promise<string>;
+  };
+}