@public-tauri/raycast-convert 1.0.1 → 1.1.0

package/src/index.ts

@@ -1,73 +1,167 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { installAndBuild } from './build';
-import { resolveNoViewCommands } from './commands';
-import { copyAssetsDir, readJson, writeJson } from './files';
+import { resolveSupportedCommands } from './commands';
+import {
+  copyRaycastViewTemplateAppDist,
+  copyRaycastWorkerViewBundle,
+  ensureRaycastViewTemplateBuilt,
+  findPublicTauriRepoRoot,
+} from './generate/copy-templates';
+import { copyPluginSourceToOutput, readJson, writeJson } from './files';
 import { generatePublicMain } from './generate/public-main';
 import { generateServerModule } from './generate/server-module';
 import { generateTsdownConfig } from './generate/tsdown-config';
 import { DEFAULT_PLUGIN_ICON, normalizeRaycastIcon } from './icons';
 import { resolveConvertOptions } from './options';
 import { createConvertedPackage } from './package-json';
+import { resolveConvertedPackageName } from './package-name';
 import { mergePreferences } from './preferences';
-import type { ConversionReport, ConvertOptions, ConvertWarning, RaycastPackage } from './types';
+import type {
+  ConversionReport,
+  ConvertOptions,
+  ConvertWarning,
+  ConvertedCommand,
+  RaycastCommandArgument,
+  RaycastPackage,
+} from './types';
 
 export type * from './types';
+export { RAYCAST_CONVERTED_SCOPE, resolveConvertedPackageName, resolveRaycastSlug, sanitizeSlug } from './package-name';
 
-const createPublicCommands = (commands: { name: string, title?: string, subtitle?: string, description?: string, icon?: string, keywords?: string[] }[], icon: string) => commands.map(command => ({
-  name: command.name,
-  title: command.title || command.name,
-  subtitle: command.subtitle || command.description,
-  description: command.description,
-  icon: normalizeRaycastIcon(command.icon) || icon,
-  mode: 'none',
-  matches: [
-    {
-      type: 'text',
-      keywords: command.keywords?.length ? command.keywords : [command.title || command.name],
-    },
-  ],
-}));
+/**
+ * `development` 模式下 view 插件的 wujie 入口：指向 `@public-tauri/template` 的 Vite 默认端口下的 `raycast.html`，
+ * 便于先 `pnpm --filter @public-tauri/template dev` 再转换插件即可调试 UI，无需模板 `build`/拷贝 `dist/view`。
+ * `production` 模式使用 `./dist/view/raycast.html`。
+ */
+export const RAYCAST_VIEW_TEMPLATE_DEV_ENTRY = 'http://localhost:5173/raycast.html';
+
+const createPublicCommands = (
+  commands: ConvertedCommand[],
+  icon: string,
+) => commands.map((command) => {
+  const raycastArguments = (command.arguments || []).map((arg: RaycastCommandArgument) => ({
+    name: arg.name,
+    type: arg.type,
+    placeholder: arg.placeholder,
+    required: Boolean(arg.required),
+    data: arg.type === 'dropdown'
+      ? (arg.data || []).map(item => ({ title: item.title || item.value, value: item.value }))
+      : undefined,
+  }));
+  return {
+    name: command.name,
+    title: command.title || command.name,
+    subtitle: command.subtitle || command.description,
+    description: command.description,
+    icon: normalizeRaycastIcon(command.icon) || icon,
+    mode: (command.mode === 'no-view' && raycastArguments.length === 0) ? 'none' : 'view',
+    raycastTargetMode: command.mode,
+    raycastArguments,
+    matches: [
+      {
+        type: 'text',
+        keywords: command.keywords?.length ? command.keywords : [command.title || command.name],
+      },
+    ],
+  };
+});
 
 export const convertRaycastPlugin = async (rawOptions: ConvertOptions): Promise<ConversionReport> => {
   const options = resolveConvertOptions(rawOptions);
   const warnings: ConvertWarning[] = [];
   const sourcePackage = await readJson<RaycastPackage>(path.join(options.inputDir, 'package.json'));
+  const convertedPackageName = resolveConvertedPackageName(sourcePackage, options.inputDir);
   const sourceCommands = sourcePackage.commands || [];
-  const { convertedCommands, skippedCommands } = await resolveNoViewCommands(options.inputDir, sourceCommands);
+  const { convertedCommands, skippedCommands } = await resolveSupportedCommands(options.inputDir, sourceCommands);
+
+  const noViewCommands = convertedCommands.filter(command => command.mode === 'no-view');
+  const viewCommands = convertedCommands.filter(command => command.mode === 'view');
+  const hasViewCommands = viewCommands.length > 0;
+  const viewHtmlUsesDevServer = hasViewCommands && options.mode === 'development';
 
   await fs.rm(options.outputDir, { recursive: true, force: true });
+  await copyPluginSourceToOutput(options.inputDir, options.outputDir);
   await fs.mkdir(options.buildDir, { recursive: true });
   await fs.mkdir(options.distDir, { recursive: true });
-  await copyAssetsDir(options.inputDir, options.assetsDir);
 
   const icon = normalizeRaycastIcon(sourcePackage.icon || convertedCommands[0]?.icon) || DEFAULT_PLUGIN_ICON;
   const commandPreferences = convertedCommands.flatMap(command => command.preferences || []);
   const preferences = mergePreferences(sourcePackage.preferences || [], commandPreferences, warnings);
   const publicCommands = createPublicCommands(convertedCommands, icon);
   const publicPlugin = {
-    title: sourcePackage.title || sourcePackage.name,
-    subtitle: sourcePackage.description || sourcePackage.name,
+    title: sourcePackage.title || sourcePackage.name || convertedPackageName,
+    subtitle: sourcePackage.description || sourcePackage.name || convertedPackageName,
     description: sourcePackage.description,
     icon,
-    main: './dist/public-main.js',
+    ...(noViewCommands.length ? { main: './dist/public-main.js' } : {}),
     server: './dist/server.js',
+    ...(viewCommands.length
+      ? { html: viewHtmlUsesDevServer ? RAYCAST_VIEW_TEMPLATE_DEV_ENTRY : './dist/view/raycast.html' }
+      : {}),
     ...(preferences.length ? { preferences } : {}),
     commands: publicCommands,
   };
 
   await writeJson(path.join(options.outputDir, 'package.json'), createConvertedPackage(sourcePackage, publicPlugin, {
+    convertedPackageName,
     publicApiDependency: options.publicApiDependency,
     warnings,
+    hasViewCommands,
   }));
-  await fs.writeFile(path.join(options.buildDir, 'public-main.ts'), generatePublicMain(), 'utf8');
-  await fs.writeFile(path.join(options.buildDir, 'server.ts'), generateServerModule(convertedCommands, sourcePackage.name, publicCommands), 'utf8');
-  await fs.writeFile(path.join(options.outputDir, 'tsdown.config.ts'), generateTsdownConfig(options), 'utf8');
+
+  if (noViewCommands.length) {
+    await fs.writeFile(path.join(options.buildDir, 'public-main.ts'), generatePublicMain(), 'utf8');
+  }
+  await fs.writeFile(
+    path.join(options.buildDir, 'server.ts'),
+    generateServerModule(
+      { noView: noViewCommands, view: viewCommands },
+      convertedPackageName,
+      publicCommands,
+      {
+        inputDir: options.inputDir,
+        outputDir: options.outputDir,
+        buildDir: options.buildDir,
+      },
+    ),
+    'utf8',
+  );
+
+  let raycastViewRepoRoot: string | null = null;
+  if (hasViewCommands) {
+    copyRaycastWorkerViewBundle(options.buildDir);
+    if (viewHtmlUsesDevServer) {
+      raycastViewRepoRoot = null;
+    } else {
+      raycastViewRepoRoot = findPublicTauriRepoRoot(options.invocationDir)
+        ?? findPublicTauriRepoRoot(process.cwd());
+      if (!raycastViewRepoRoot) {
+        throw new Error('Could not locate Public Tauri repo root (pnpm-workspace.yaml + packages/api). '
+          + 'Run raycast-convert from the monorepo, set invocationDir, or copy packages/template dist into dist/view manually.');
+      }
+      ensureRaycastViewTemplateBuilt(raycastViewRepoRoot);
+      if (!options.build) {
+        copyRaycastViewTemplateAppDist(raycastViewRepoRoot, options.distDir);
+      }
+    }
+  }
+
+  await fs.writeFile(path.join(options.outputDir, 'tsdown.config.ts'), generateTsdownConfig(options, {
+    hasPublicMain: noViewCommands.length > 0,
+  }), 'utf8');
 
   const report: ConversionReport = {
     source: options.inputDir,
     output: options.outputDir,
-    convertedCommands: convertedCommands.map(command => ({ name: command.name, entry: command.entry })),
+    sourcePackageName: typeof sourcePackage.name === 'string' ? sourcePackage.name : undefined,
+    convertedPackageName,
+    convertedCommands: convertedCommands.map((command) => {
+      const outputEntry = path.join(options.outputDir, path.relative(path.resolve(options.inputDir), path.resolve(command.entry)));
+      const entry = path.relative(options.outputDir, outputEntry).split(path.sep)
+        .join('/') || '.';
+      return { name: command.name, entry };
+    }),
     skippedCommands,
     warnings,
   };
@@ -75,6 +169,10 @@ export const convertRaycastPlugin = async (rawOptions: ConvertOptions): Promise<
 
   if (options.build) {
     installAndBuild(options);
+    // tsdown 会清空 `dist/`；view 子应用在 tsdown 之后重新拷贝
+    if (hasViewCommands && raycastViewRepoRoot) {
+      copyRaycastViewTemplateAppDist(raycastViewRepoRoot, options.distDir);
+    }
   }
 
   return report;

package/src/options.ts

@@ -1,12 +1,46 @@
+import fs from 'node:fs';
 import path from 'node:path';
 import type { ConvertMode, ConvertOptions, ResolvedConvertOptions } from './types';
 
 const resolveMode = (mode: ConvertOptions['mode']): ConvertMode => mode || 'development';
 
+/**
+ * 自 startDir 向上查找 monorepo 根（pnpm-workspace.yaml + packages/api），避免依赖 process.cwd()
+ *（例如从 src-node、src-node/src 启动 Node 时 cwd 并非仓库根）。
+ */
+const findPublicTauriRepoRoot = (startDir: string): string | undefined => {
+  let dir = path.resolve(startDir);
+  const { root } = path.parse(dir);
+  while (dir !== root) {
+    const ws = path.join(dir, 'pnpm-workspace.yaml');
+    const apiPkg = path.join(dir, 'packages', 'api', 'package.json');
+    if (fs.existsSync(ws) && fs.existsSync(apiPkg)) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return undefined;
+};
+
+const resolveInvocationDir = (options: ConvertOptions): string => {
+  if (options.invocationDir) {
+    return path.resolve(options.invocationDir);
+  }
+  const mode = resolveMode(options.mode);
+  if (mode !== 'development') {
+    return path.resolve(process.cwd());
+  }
+  const fromRoot = findPublicTauriRepoRoot(process.cwd());
+  if (fromRoot) {
+    return fromRoot;
+  }
+  throw new Error('development 模式需要定位 monorepo 根目录（含 pnpm-workspace.yaml 与 packages/api）。请在仓库内执行、设置 invocationDir，或改用 production 模式。');
+};
+
 export const resolveConvertOptions = (options: ConvertOptions): ResolvedConvertOptions => {
   const inputDir = path.resolve(options.inputDir);
   const outputDir = path.resolve(options.outputDir || `${inputDir}-public`);
-  const invocationDir = path.resolve(options.invocationDir || process.cwd());
+  const invocationDir = resolveInvocationDir(options);
   const mode = resolveMode(options.mode);
 
   return {
@@ -18,6 +52,5 @@ export const resolveConvertOptions = (options: ConvertOptions): ResolvedConvertO
     publicApiDependency: mode === 'development' ? `file:${path.join(invocationDir, 'packages', 'api')}` : 'latest',
     buildDir: path.join(outputDir, '.raycast-build'),
     distDir: path.join(outputDir, 'dist'),
-    assetsDir: path.join(outputDir, 'assets'),
   };
 };

package/src/package-json.ts

@@ -1,15 +1,10 @@
 import type { ConvertWarning, RaycastPackage } from './types';
 
-const raycastApiPackages = new Set(['@raycast/api', '@raycast/utils']);
-
 const rewriteDependencyMap = (dependencies: Record<string, string> | undefined) => {
   const rewritten = { ...(dependencies || {}) };
-  let replacedRaycastApi = false;
-  for (const packageName of raycastApiPackages) {
-    if (packageName in rewritten) {
-      delete rewritten[packageName];
-      replacedRaycastApi = true;
-    }
+  const replacedRaycastApi = '@raycast/api' in rewritten;
+  if (replacedRaycastApi) {
+    delete rewritten['@raycast/api'];
   }
   return { dependencies: rewritten, replacedRaycastApi };
 };
@@ -17,19 +12,25 @@ const rewriteDependencyMap = (dependencies: Record<string, string> | undefined)
 export const createConvertedPackage = (
   sourcePackage: RaycastPackage,
   publicPlugin: Record<string, unknown>,
-  options: { publicApiDependency: string, warnings: ConvertWarning[] },
+  options: {
+    convertedPackageName: string,
+    publicApiDependency: string,
+    warnings: ConvertWarning[],
+    hasViewCommands?: boolean,
+  },
 ) => {
   const dependenciesResult = rewriteDependencyMap(sourcePackage.dependencies);
   const devDependenciesResult = rewriteDependencyMap(sourcePackage.devDependencies);
   if (dependenciesResult.replacedRaycastApi || devDependenciesResult.replacedRaycastApi) {
     options.warnings.push({
       type: 'dependency',
-      message: 'Replaced @raycast/api and/or @raycast/utils with @public-tauri/api',
+      message: 'Replaced @raycast/api with @public-tauri/api (see tsdown alias); @raycast/utils is left as declared',
     });
   }
 
   return {
     ...sourcePackage,
+    name: options.convertedPackageName,
     version: sourcePackage.version || '1.0.0',
     type: 'module',
     private: true,
@@ -41,10 +42,17 @@ export const createConvertedPackage = (
     dependencies: {
       ...dependenciesResult.dependencies,
       '@public-tauri/api': dependenciesResult.dependencies['@public-tauri/api'] || options.publicApiDependency,
+      ...(options.hasViewCommands ? {
+        react: dependenciesResult.dependencies.react || '^19.0.0',
+        'react-reconciler': dependenciesResult.dependencies['react-reconciler'] || '^0.31.0',
+      } : {}),
     },
     devDependencies: {
       ...devDependenciesResult.dependencies,
       tsdown: devDependenciesResult.dependencies.tsdown || '^0.21.7',
+      ...(options.hasViewCommands ? {
+        '@types/react': devDependenciesResult.dependencies['@types/react'] || '^19.0.0',
+      } : {}),
     },
   };
 };

package/src/package-name.ts

@@ -0,0 +1,40 @@
+import path from 'node:path';
+import type { RaycastPackage } from './types';
+
+export const RAYCAST_CONVERTED_SCOPE = '@public-tauri-raycast';
+
+/** npm 包名片段：与 npm 命名惯例对齐的小写、符号规整 */
+export const sanitizeSlug = (raw: string): string => {
+  let segment = raw.trim().toLowerCase()
+    .replace(/[^a-z0-9._-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (!segment || /^[._]/.test(segment)) {
+    segment = `plugin-${segment || 'unnamed'}`.replace(/^-+/, '');
+  }
+  return segment || 'raycast-plugin';
+};
+
+/**
+ * 未 scope 的 Raycast 官方插件：一般为单段名字 → `@public-tauri-raycast/<slug>`。
+ * 若将来出现 scoped：`@my-scope/xxx` → `@public-tauri-raycast/my-scope_xxx`。
+ */
+export const resolveRaycastSlug = (sourcePackage: RaycastPackage, inputDir: string): string => {
+  const raw = typeof sourcePackage.name === 'string' ? sourcePackage.name.trim() : '';
+  if (raw.startsWith('@')) {
+    const slash = raw.indexOf('/');
+    if (slash !== -1) {
+      const scope = raw.slice(1, slash);
+      const pkg = raw.slice(slash + 1);
+      return `${sanitizeSlug(scope)}_${sanitizeSlug(pkg)}`;
+    }
+    return sanitizeSlug(raw.slice(1));
+  }
+  if (raw) {
+    return sanitizeSlug(raw);
+  }
+  return sanitizeSlug(path.basename(path.resolve(inputDir)));
+};
+
+export const resolveConvertedPackageName = (sourcePackage: RaycastPackage, inputDir: string): string =>
+  `${RAYCAST_CONVERTED_SCOPE}/${resolveRaycastSlug(sourcePackage, inputDir)}`;

package/src/types.ts

@@ -11,6 +11,21 @@ export type RaycastPreference = {
   data?: { title?: string, label?: string, value: string | number | boolean }[];
 };
 
+export type RaycastCommandArgumentType = 'text' | 'password' | 'dropdown';
+
+export type RaycastCommandArgumentOption = {
+  title?: string;
+  value: string;
+};
+
+export type RaycastCommandArgument = {
+  name: string;
+  placeholder?: string;
+  type: RaycastCommandArgumentType;
+  required?: boolean;
+  data?: RaycastCommandArgumentOption[];
+};
+
 export type RaycastCommand = {
   name: string;
   title?: string;
@@ -20,10 +35,11 @@ export type RaycastCommand = {
   keywords?: string[];
   icon?: string;
   preferences?: RaycastPreference[];
+  arguments?: RaycastCommandArgument[];
 };
 
 export type RaycastPackage = {
-  name: string;
+  name?: string;
   version?: string;
   type?: string;
   title?: string;
@@ -41,8 +57,11 @@ export type ConvertWarning = {
   message: string;
 };
 
+export type SupportedRaycastCommandMode = 'no-view' | 'view';
+
 export type ConvertedCommand = RaycastCommand & {
   entry: string;
+  mode: SupportedRaycastCommandMode;
 };
 
 export type ConvertMode = 'development' | 'production';
@@ -61,12 +80,15 @@ export type ResolvedConvertOptions = Required<Omit<ConvertOptions, 'outputDir' |
   publicApiDependency: string;
   buildDir: string;
   distDir: string;
-  assetsDir: string;
 };
 
 export type ConversionReport = {
   source: string;
   output: string;
+  /** Raycast extension package.json name before conversion (may be missing). */
+  sourcePackageName?: string;
+  /** Converted Public plugin npm name, e.g. @public-tauri-raycast/screenshot */
+  convertedPackageName: string;
   convertedCommands: { name: string, entry: string }[];
   skippedCommands: { name: string, reason: string }[];
   warnings: ConvertWarning[];

package/templates/host-instance.ts

@@ -0,0 +1,35 @@
+/**
+ * Custom reconciler 内部的宿主节点（与 React fiber 解耦后的最小树）。
+ * 序列化层直接遍历该结构生成可 JSON 化的 VirtualNode。
+ */
+
+export type HostTextInstance = {
+  type: 'text';
+  /** 宿主分配的不透明 id，序列化与事件派发与 RN reactTag 同类 */
+  hostId: string;
+  text: string;
+  parent: HostElementInstance | HostRootContainer | null;
+};
+
+export type HostElementInstance = {
+  type: string;
+  hostId: string;
+  props: Record<string, unknown>;
+  parent: HostElementInstance | HostRootContainer | null;
+  children: HostInstance[];
+};
+
+/** createContainer 的根容器，仅含 children */
+export type HostRootContainer = {
+  children: HostInstance[];
+};
+
+export type HostInstance = HostTextInstance | HostElementInstance;
+
+export function isHostText(n: HostInstance): n is HostTextInstance {
+  return n.type === 'text';
+}
+
+export function isHostElement(n: HostInstance): n is HostElementInstance {
+  return n.type !== 'text';
+}

package/templates/json-patch.ts

@@ -0,0 +1,166 @@
+/**
+ * Minimal JSON Patch (RFC 6902) diff generator.
+ *
+ * Tailored for the Raycast view snapshot tree:
+ * - Objects with a `hostId` field in arrays are matched by `hostId` for stable diffing.
+ * - Arrays without `hostId` items are compared index-by-index.
+ */
+
+export type JsonPatchOp =
+  | { op: 'add'; path: string; value: unknown }
+  | { op: 'remove'; path: string }
+  | { op: 'replace'; path: string; value: unknown };
+
+function escapePointer(s: string | number): string {
+  return String(s).replace(/~/g, '~0')
+    .replace(/\//g, '~1');
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function hasHostId(v: unknown): v is { hostId: string;[k: string]: unknown } {
+  return isObject(v) && typeof v.hostId === 'string';
+}
+
+function diffValue(oldVal: unknown, newVal: unknown, path: string, ops: JsonPatchOp[]): void {
+  if (oldVal === newVal) return;
+
+  if (oldVal === null || oldVal === undefined || newVal === null || newVal === undefined) {
+    if (oldVal !== newVal) ops.push({ op: 'replace', path, value: newVal });
+    return;
+  }
+
+  if (typeof oldVal !== typeof newVal) {
+    ops.push({ op: 'replace', path, value: newVal });
+    return;
+  }
+
+  if (typeof oldVal !== 'object') {
+    if (oldVal !== newVal) ops.push({ op: 'replace', path, value: newVal });
+    return;
+  }
+
+  const isOldArr = Array.isArray(oldVal);
+  const isNewArr = Array.isArray(newVal);
+  if (isOldArr !== isNewArr) {
+    ops.push({ op: 'replace', path, value: newVal });
+    return;
+  }
+
+  if (isOldArr && isNewArr) {
+    diffArray(oldVal as unknown[], newVal as unknown[], path, ops);
+    return;
+  }
+
+  diffObject(
+    oldVal as Record<string, unknown>,
+    newVal as Record<string, unknown>,
+    path,
+    ops,
+  );
+}
+
+/**
+ * Diff two arrays. If both contain objects with `hostId`, use hostId-based
+ * matching so that insertions/deletions don't cause cascading replace ops on
+ * every subsequent element.
+ */
+function diffArray(oldArr: unknown[], newArr: unknown[], path: string, ops: JsonPatchOp[]): void {
+  const allOldHostId = oldArr.length > 0 && oldArr.every(hasHostId);
+  const allNewHostId = newArr.length > 0 && newArr.every(hasHostId);
+
+  if (allOldHostId && allNewHostId) {
+    diffHostIdArray(oldArr as { hostId: string;[k: string]: unknown }[], newArr as { hostId: string;[k: string]: unknown }[], path, ops);
+    return;
+  }
+
+  diffIndexArray(oldArr, newArr, path, ops);
+}
+
+function diffIndexArray(oldArr: unknown[], newArr: unknown[], path: string, ops: JsonPatchOp[]): void {
+  const minLen = Math.min(oldArr.length, newArr.length);
+  for (let i = 0; i < minLen; i++) {
+    diffValue(oldArr[i], newArr[i], `${path}/${i}`, ops);
+  }
+  for (let i = minLen; i < newArr.length; i++) {
+    ops.push({ op: 'add', path: `${path}/-`, value: newArr[i] });
+  }
+  for (let i = oldArr.length - 1; i >= newArr.length; i--) {
+    ops.push({ op: 'remove', path: `${path}/${i}` });
+  }
+}
+
+/**
+ * Diff arrays whose elements each have a `hostId`.
+ * Match by hostId so re-ordering or insertions produce minimal patches.
+ * If the order of shared hostIds diverges, fall back to a wholesale replace.
+ */
+function diffHostIdArray(
+  oldArr: { hostId: string;[k: string]: unknown }[],
+  newArr: { hostId: string;[k: string]: unknown }[],
+  path: string,
+  ops: JsonPatchOp[],
+): void {
+  const oldMap = new Map(oldArr.map((item, i) => [item.hostId, { item, index: i }]));
+  const newMap = new Map(newArr.map((item, i) => [item.hostId, { item, index: i }]));
+
+  const sharedOldOrder = oldArr.filter(o => newMap.has(o.hostId)).map(o => o.hostId);
+  const sharedNewOrder = newArr.filter(n => oldMap.has(n.hostId)).map(n => n.hostId);
+
+  const orderChanged =    sharedOldOrder.length !== sharedNewOrder.length
+    || sharedOldOrder.some((id, i) => id !== sharedNewOrder[i]);
+
+  if (orderChanged) {
+    ops.push({ op: 'replace', path, value: newArr });
+    return;
+  }
+
+  const removedIds = oldArr.filter(o => !newMap.has(o.hostId)).map(o => o.hostId);
+  for (let i = oldArr.length - 1; i >= 0; i--) {
+    if (removedIds.includes(oldArr[i].hostId)) {
+      ops.push({ op: 'remove', path: `${path}/${i}` });
+    }
+  }
+
+  const kept = oldArr.filter(o => newMap.has(o.hostId));
+  for (const oldItem of kept) {
+    const newEntry = newMap.get(oldItem.hostId)!;
+    diffValue(oldItem, newEntry.item, `${path}/${newEntry.index}`, ops);
+  }
+
+  const addedEntries = newArr
+    .map((item, i) => ({ item, index: i }))
+    .filter(e => !oldMap.has(e.item.hostId));
+  for (const entry of addedEntries) {
+    ops.push({ op: 'add', path: `${path}/${entry.index}`, value: entry.item });
+  }
+}
+
+function diffObject(
+  oldObj: Record<string, unknown>,
+  newObj: Record<string, unknown>,
+  path: string,
+  ops: JsonPatchOp[],
+): void {
+  for (const key of Object.keys(oldObj)) {
+    if (!(key in newObj)) {
+      ops.push({ op: 'remove', path: `${path}/${escapePointer(key)}` });
+    }
+  }
+  for (const key of Object.keys(newObj)) {
+    const p = `${path}/${escapePointer(key)}`;
+    if (!(key in oldObj)) {
+      ops.push({ op: 'add', path: p, value: newObj[key] });
+    } else {
+      diffValue(oldObj[key], newObj[key], p, ops);
+    }
+  }
+}
+
+export function generateJsonPatch(oldVal: unknown, newVal: unknown): JsonPatchOp[] {
+  const ops: JsonPatchOp[] = [];
+  diffValue(oldVal, newVal, '', ops);
+  return ops;
+}

package/templates/raycast-view-protocol.ts

@@ -0,0 +1,43 @@
+/** Worker 下发给视图端的宿主树快照（JSON-safe）。 */
+
+/**
+ * 函数型 prop 在快照中的占位前缀；完整 token 为 `${RAYCAST_SERIALIZED_FUNC_PREFIX}${propName}`（propName 即 Worker Registry 事件名，如 `onAction`）。
+ * 视图端应反序列化为可调函数并 `channel.invoke('raycast:view:run-action', { commandName, hostId, event: propName, args })`。
+ */
+export const RAYCAST_SERIALIZED_FUNC_PREFIX = '__func__';
+
+export type { JsonPatchOp } from './json-patch';
+
+export type SerializedHostElementNode = {
+  hostId: string;
+  type: string;
+  props: Record<string, unknown>;
+  children: SerializedHostNode[];
+};
+
+export type SerializedHostNode =
+  | { hostId: string; type: 'text'; text: string }
+  | SerializedHostElementNode;
+
+export type RaycastViewSnapshot = {
+  commandName: string;
+  root: SerializedHostNode;
+  error?: string;
+};
+
+export type RaycastViewMountPayload = {
+  commandName: string;
+  query?: string;
+  preferences?: Record<string, unknown>;
+  options?: Record<string, unknown>;
+};
+
+/** run-action 通道：hostId 为 SerializedHostNode.hostId（含 props slot 内合成的 rv:p:*） */
+export type RaycastViewDispatchPayload = {
+  commandName: string;
+  hostId: string;
+  /** 缺省为 onAction；与序列化 token 中 prop 名一致 */
+  event?: string;
+  /** 透传给 Worker 端 handler（`handlers.get(hostId + ':' + event)`） */
+  args?: unknown[];
+};