vscode-behavior3 2.2.0 → 2.3.0

package/README.md

@@ -1,212 +1,185 @@
 # Behavior3 Editor
 
-VS Code behavior tree visual editor for game AI workflows.
+VS Code custom editor for Behavior3 JSON behavior trees. It combines a visual graph canvas, an Inspector, project scaffolding, and build/check/batch scripting for game AI workflows.
 
 ## Related Projects
 
-- **[behavior3-ts](https://github.com/codetypess/behavior3-ts)** - TypeScript Runtime Library
-- **[behavior3lua](https://github.com/zhandouxiaojiji/behavior3lua)** - Lua Runtime
+- **[behavior3-ts](https://github.com/codetypess/behavior3-ts)** - TypeScript runtime library
+- **[behavior3lua](https://github.com/zhandouxiaojiji/behavior3lua)** - Lua runtime
 
-## Editor Preview
+## Preview
 
 ![Behavior3 Editor Preview](media/images/pic.png)
 
-The editor provides an intuitive visual interface for designing and managing behavior trees. See the screenshot above for the full editing experience with node canvas, inspector panel, and tree organization.
-
 ## Features
 
-- Visual canvas editor (drag, connect, organize nodes)
-- Built-in inspector panel for node/tree properties
+- Visual graph editor for Behavior3 trees and reachable subtrees
+- Inspector in `sidebar` or `embedded` mode
+- Explorer `Behavior3` submenu for project, tree, and script scaffolding
+- Build, debug build, checker scripts, and project batch processing
 - Custom node definitions via `.b3-setting`
-- One-click build command in editor title bar
-- Optional expression validation for node args
-- Auto theme adaptation (dark/light)
+- Expression and node-argument validation
+- Theme-aware UI for dark and light VS Code themes
 
 ## Quick Start
 
-### Open a tree file
+### Open a tree
+
+- Right-click a Behavior3 `.json` file in Explorer
+- Select **Open With** -> **Behavior3 Editor**
 
-- Right-click a tree `.json` file in Explorer
-- Select **Open With** → **Behavior3 Editor**
+### Create project files
 
-### Create a new project
+From a folder's Explorer `Behavior3` submenu you can run:
 
-- Right-click a folder in Explorer
-- Run **Behavior Tree: Create Project**
+- **Create Project**
+- **Create Behavior Tree File**
+- **Create Build Script**
+- **Create Batch Script**
+- **Create Checker Script**
+- **Run Script as Batch Process**
 
-### Configure nodes
+`Run Script as Batch Process` is also available on `.ts`, `.mts`, `.js`, and `.mjs` files. Running it from a folder lets you choose a script first; running it from a script file runs that script directly.
 
-Create a `.b3-setting` file in workspace:
+### Configure node definitions
+
+Create a `.b3-setting` file in the workspace:
 
 ```json
 [
-    {
-        "name": "MyAction",
-        "type": "Action",
-        "desc": "Does something useful",
-        "args": [{ "name": "duration", "type": "float", "desc": "Duration in seconds" }]
-    },
-    {
-        "name": "CheckScore",
-        "type": "Condition",
-        "desc": "Checks whether the score matches the rule",
-        "args": [{ "name": "value", "type": "expr", "desc": "Expression" }]
-    }
+  {
+    "name": "MyAction",
+    "type": "Action",
+    "desc": "Does something useful",
+    "args": [{ "name": "duration", "type": "float", "desc": "Duration in seconds" }]
+  },
+  {
+    "name": "CheckScore",
+    "type": "Condition",
+    "desc": "Checks whether the score matches the rule",
+    "args": [{ "name": "value", "type": "expr", "desc": "Expression" }]
+  }
 ]
 ```
 
-### Build
-
-Click **Build** in the editor title bar.
+### Configure workspace behavior
 
-### Command Line Build
-
-The npm package exposes a `behavior3-build` command for CI and project scripts:
-
-```bash
-npm install -D vscode-behavior3
-```
+Use a `.b3-workspace` file to register build and checker scripts:
 
 ```json
 {
-    "scripts": {
-        "build:behavior": "behavior3-build --project ./workdir/hero.json --output ./dist/behavior3"
-    }
+  "settings": {
+    "checkExpr": true,
+    "buildScript": "scripts/build.ts",
+    "checkScripts": ["scripts/checkers/**/*.ts"]
+  }
 }
 ```
 
-You can also run it without adding a script:
-
-```bash
-npm exec -- behavior3-build --project ./workdir/hero.json --output ./dist/behavior3
-```
-
-Or run it without installing first:
+`buildScript` and `checkScripts` are resolved relative to the `.b3-workspace` file. See [sample/workspace.b3-workspace](sample/workspace.b3-workspace) for a complete sample.
 
-```bash
-npx --package vscode-behavior3 behavior3-build --project ./workdir/hero.json --output ./dist/behavior3
-```
+## Inspector Modes
 
-Publishing flow:
+Set `behavior3.inspectorMode` to choose the active Inspector presentation:
 
-```bash
-npm login
-npm whoami
-npm version patch
-npm run pack:npm
-npm run publish:npm
-```
+- `sidebar`: show the Inspector in the dedicated Behavior3 side view
+- `embedded`: show the Inspector inside the main editor webview
 
-`npm run pack:npm` performs the same prepack checks as publishing and prints the
-tarball contents without publishing.
+Both modes share the same document semantics and commands. Only the presentation changes.
 
-### Build Script (`.b3-workspace`)
+## Build, Batch, and Check Scripts
 
-`settings.buildScript` supports ESM scripts:
+Behavior3 supports ESM JavaScript and TypeScript scripts:
 
 - JavaScript: `.js`, `.mjs`
 - TypeScript: `.ts`, `.mts` (runtime transpile, no type-check)
 
-TypeScript build scripts can import other local TypeScript files with explicit
-extensions:
+When importing local TypeScript helpers, use explicit extensions such as `./helper.ts`.
+The `behavior3` decorator namespace is provided by the runtime, so script files only need type imports from `vscode-behavior3/build`.
 
-```ts
-import { helper } from "./helper.ts";
-```
+All script types can import authoring types from `vscode-behavior3/build`. Example scripts are available in:
 
-To debug TypeScript build scripts, launch the CLI with Node inspector and enable
-build-script debug mode:
+- [sample/scripts/build.ts](sample/scripts/build.ts)
+- [sample/scripts/batch.ts](sample/scripts/batch.ts)
+- [sample/scripts/checkers/positive.ts](sample/scripts/checkers/positive.ts)
 
-```bash
-BEHAVIOR3_BUILD_DEBUG=1 node --inspect-brk dist/build-cli.js --output /tmp/b3build --project sample/workdir/hero.json
-```
+### Build Scripts
 
-This emits inline source maps and creates temporary `.runtime.*.mjs` files next
-to the build script while the build runs so breakpoints in `build.ts` and
-imported helper files can bind. The runtime files are removed after the build
-completes; if the build script fails to load, they are left in place for
-inspection. Editor debug builds also clean runtime files when the debug session
-terminates.
-Inside the editor, `Ctrl+B`/`Cmd+B` builds normally, while
-`Ctrl+Shift+B`/`Cmd+Shift+B` starts a VS Code Node debug session for the build.
+Build scripts are declared with `@behavior3.build` and can transform build output without rewriting source trees.
 
-Example:
+```ts
+import type { BuildEnv, BuildScript } from "vscode-behavior3/build";
 
-```json
-{
-    "settings": {
-        "checkExpr": true,
-        "buildScript": "scripts/build.ts",
-        "checkScripts": ["scripts/checkers/**/*.ts"]
-    }
+@behavior3.build
+export class ProjectBuild implements BuildScript {
+  constructor(private readonly env: BuildEnv) {}
 }
 ```
 
-`settings.checkScripts` is optional and loads additional checker-only scripts
-relative to the `.b3-workspace` directory. Matching scripts are scanned for
-exported `@behavior3.check("name")` classes and are used by both the editor
-Inspector validation and project builds. Generated `.runtime.*.mjs`, `.d.ts`,
-`node_modules`, `dist`, and `build` paths are ignored.
+Supported hooks:
 
-All build hooks receive `env`:
+- `onProcessTree(tree, path, errors)`
+- `onProcessNode(node, errors)`
+- `onWriteFile(path, tree)`
+- `onComplete(status)`
+
+### Batch Scripts
 
-- `env.fs`: Node `fs`
-- `env.path`: full path helper object (all methods exposed)
-- `env.workdir`: resolved workspace directory
-- `env.nodeDefs`: loaded node definitions map
-- `env.logger`: `log/debug/info/warn/error`
+Batch scripts are declared with `@behavior3.batch` and are used by **Run Script as Batch Process** to rewrite source trees in place across the current project.
 
-Use an exported `@behavior3.build` class. The decorator is provided by the build
-runtime, so no value import is required. The extension constructs the class once
-with `env`, then calls methods:
+Supported hooks:
 
-- `constructor(env)`
 - `shouldUpgradeTree(path, tree)`
 - `onProcessTree(tree, path, errors)`
 - `onProcessNode(node, errors)`
 - `onWriteFile(path, tree)`
 - `onComplete(status)`
 
-```ts
-import type { BuildEnv, TreeData } from "vscode-behavior3/build";
+### Checker Scripts
 
-@behavior3.build
-export class ProjectBuild {
-    constructor(private readonly env: BuildEnv) {}
+Checker scripts register custom argument validators with `@behavior3.check("name")`. They are used by both Inspector validation and project builds.
 
-    onProcessTree(tree: TreeData) {
-        this.env.logger.info("building", tree.name);
-        return tree;
-    }
-}
-```
+For compatibility, supported script files may still export classes through named `Hook`, `BuildHook`, `BatchHook`, or `default`, but the decorator-based forms above are the canonical APIs.
 
-For compatibility, supported script files may still export a class via named
-`Hook` or `default`.
+## Build and Debug
 
-For TypeScript authoring hints, import build script types from
-`vscode-behavior3/build`. See `sample/scripts/build.ts` for a complete example.
+- Click **Build** in the editor title bar, or press `Ctrl/Cmd+B`
+- Press `Ctrl/Cmd+Shift+B` to start a debug build session
 
-### Project Batch Processing
+The npm package also exposes a `behavior3-build` command for CI and project scripts:
 
-Use `Batch Process Behavior Trees` to pick a script on demand and apply it to
-every behavior tree source file in the current project. The script can be
-TypeScript with local `import` statements, just like build scripts.
+```bash
+npm install -D vscode-behavior3
+```
 
-## Extension Settings
+```json
+{
+  "scripts": {
+    "build:behavior": "behavior3-build --project ./workdir/hero.json --output ./dist/behavior3"
+  }
+}
+```
 
-| Setting               | Type    | Default  | Description                                                      |
-| --------------------- | ------- | -------- | ---------------------------------------------------------------- |
-| `behavior3.checkExpr` | boolean | `true`   | Enable expression syntax validation for expression-type args.    |
-| `behavior3.language`  | string  | `"auto"` | Editor UI language. Options:`auto` (follow VS Code), `zh`, `en`. |
+You can also run it directly:
 
-## Inspector
+```bash
+npm exec -- behavior3-build --project ./workdir/hero.json --output ./dist/behavior3
+```
 
-Inspector is available in the dedicated `behavior3` sidebar and supports direct editing.
+Or without installing first:
 
-- Select a node to edit node fields (`args`, `input`, `output`, `desc`, `debug`, `disabled`)
-- Click empty canvas to edit tree fields (`name`, `desc`, `vars`, `import`, `group`)
-- Opening a Behavior3 tree or changing the graph selection will automatically reveal the matching Inspector context
+```bash
+npx --package vscode-behavior3 behavior3-build --project ./workdir/hero.json --output ./dist/behavior3
+```
+
+## Extension Settings
+
+| Setting                     | Type      | Default     | Description                                                              |
+| --------------------------- | --------- | ----------- | ------------------------------------------------------------------------ |
+| `behavior3.checkExpr`       | `boolean` | `true`      | Enable expression validation for expression-type args.                   |
+| `behavior3.language`        | `string`  | `"auto"`    | UI language: `auto`, `zh`, or `en`.                                      |
+| `behavior3.subtreeEditable` | `boolean` | `true`      | Allow editing supported subtree content from the current editor context. |
+| `behavior3.inspectorMode`   | `string`  | `"sidebar"` | Choose whether the Inspector is shown in `sidebar` or `embedded` mode.   |
 
 ## Keyboard Shortcuts
 
@@ -224,14 +197,22 @@ Inspector is available in the dedicated `behavior3` sidebar and supports direct
 | `Ctrl/Cmd+B`             | Build                          |
 | `F4`                     | Toggle Text / Behavior3 editor |
 
+## Docs
+
+- [docs/README.md](docs/README.md) - documentation entry point
+- [docs/spec-driven-development.md](docs/spec-driven-development.md) - SDD workflow
+- [docs/spec/README.md](docs/spec/README.md) - baseline spec map and work-item index
+- [sample/](sample) - sample workspace, trees, and scripts
+
 ## Development
 
-- Output logs: **View → Output** → channel **Behavior3**
+- Output logs: **View -> Output** -> **Behavior3**
 - Webview logs are also available in DevTools
 
 ## Requirements
 
-- VS Code 1.85.0+
+- VS Code `^1.105.0`
+- Node `>=20.19` for the CLI and TypeScript script runtime
 
 ## License
 

package/build.d.ts

@@ -2,9 +2,14 @@ import type { BuildRuntime } from "./webview/shared/b3build-model";
 export type { NodeDef } from "behavior3";
 export type { NodeData, TreeData } from "./webview/shared/b3type";
 export type {
+  BatchDecorator,
+  BatchHook,
+  BatchHookClass,
+  BatchScript,
   BuildEnv,
   CheckDecorator,
   BuildDecorator,
+  BuildHook,
   BuildHookClass,
   BuildLogger,
   BuildRuntime,

package/dist/build-cli.js

@@ -213347,14 +213347,15 @@ var readWorkspaceSettings = (path3) => {
   const content = getFs().readFileSync(path3, "utf-8");
   return parseWorkspaceModelContent(content).settings;
 };
-var hasBatchHookMethod = (obj) => {
+var hasBuildHookMethod = (obj) => {
   if (!obj || typeof obj !== "object") {
     return false;
   }
   const candidate = obj;
-  return typeof candidate.shouldUpgradeTree === "function" || typeof candidate.onProcessTree === "function" || typeof candidate.onProcessNode === "function" || typeof candidate.onWriteFile === "function" || typeof candidate.onComplete === "function";
+  return typeof candidate.onProcessTree === "function" || typeof candidate.onProcessNode === "function" || typeof candidate.onWriteFile === "function" || typeof candidate.onComplete === "function";
 };
 var BUILD_HOOK_MARKER = "__behavior3BuildHook";
+var BATCH_HOOK_MARKER = "__behavior3BatchHook";
 var CHECK_HOOK_MARKER = "__behavior3CheckHook";
 var CHECK_HOOK_NAME = "__behavior3CheckName";
 var markBuildHook = (ctor) => {
@@ -213364,6 +213365,13 @@ var markBuildHook = (ctor) => {
   });
   return ctor;
 };
+var markBatchHook = (ctor) => {
+  Object.defineProperty(ctor, BATCH_HOOK_MARKER, {
+    value: true,
+    configurable: false
+  });
+  return ctor;
+};
 var markCheckCtor = (ctor, explicitName) => {
   const name = explicitName?.trim() || ctor.name;
   Object.defineProperty(ctor, CHECK_HOOK_MARKER, {
@@ -213382,28 +213390,51 @@ var markCheckHook = (nameOrCtor, _context) => {
   }
   return (ctor) => markCheckCtor(ctor, nameOrCtor);
 };
-var isDecoratedHookCtor = (value) => typeof value === "function" && value[BUILD_HOOK_MARKER] === true;
+var isDecoratedBuildHookCtor = (value) => typeof value === "function" && value[BUILD_HOOK_MARKER] === true;
+var isDecoratedBatchHookCtor = (value) => typeof value === "function" && value[BATCH_HOOK_MARKER] === true;
 var isDecoratedCheckCtor = (value) => typeof value === "function" && value[CHECK_HOOK_MARKER] === true;
-var findDecoratedHookCtor = (moduleRecord) => {
-  const decorated = Array.from(new Set(Object.values(moduleRecord))).filter(isDecoratedHookCtor);
+var findDecoratedBuildHookCtor = (moduleRecord) => {
+  const decorated = Array.from(new Set(Object.values(moduleRecord))).filter(
+    isDecoratedBuildHookCtor
+  );
   if (decorated.length > 1) {
     logger.error("build script must decorate exactly one exported class with @behavior3.build");
     return void 0;
   }
   return decorated[0];
 };
+var findDecoratedBatchHookCtor = (moduleRecord) => {
+  const decorated = Array.from(new Set(Object.values(moduleRecord))).filter(
+    isDecoratedBatchHookCtor
+  );
+  if (decorated.length > 1) {
+    logger.error("batch script must decorate exactly one exported class with @behavior3.batch");
+    return void 0;
+  }
+  if (decorated.length === 1) {
+    return decorated[0];
+  }
+  const legacyDecorated = Array.from(new Set(Object.values(moduleRecord))).filter(
+    isDecoratedBuildHookCtor
+  );
+  if (legacyDecorated.length > 1) {
+    logger.error("batch script must decorate exactly one exported class with @behavior3.batch");
+    return void 0;
+  }
+  return legacyDecorated[0];
+};
 var findDecoratedCheckCtors = (moduleRecord) => Array.from(new Set(Object.values(moduleRecord))).filter(isDecoratedCheckCtor);
-var createBatchHooks = (moduleExports, env, reportMissing = true) => {
+var createBuildHooks = (moduleExports, env, reportMissing = true) => {
   if (!moduleExports || typeof moduleExports !== "object") {
     return void 0;
   }
   const moduleRecord = moduleExports;
-  const defaultExport = isDecoratedCheckCtor(moduleRecord.default) ? void 0 : moduleRecord.default;
-  const ctor = moduleRecord.Hook ?? findDecoratedHookCtor(moduleRecord) ?? defaultExport;
+  const defaultExport = isDecoratedCheckCtor(moduleRecord.default) || isDecoratedBatchHookCtor(moduleRecord.default) ? void 0 : moduleRecord.default;
+  const ctor = moduleRecord.BuildHook ?? moduleRecord.Hook ?? findDecoratedBuildHookCtor(moduleRecord) ?? defaultExport;
   if (typeof ctor === "function") {
     try {
       const instance = new ctor(env);
-      if (hasBatchHookMethod(instance)) {
+      if (hasBuildHookMethod(instance)) {
         return instance;
       }
       logger.error("build hook class instance has no supported hook methods");
@@ -213413,7 +213444,32 @@ var createBatchHooks = (moduleExports, env, reportMissing = true) => {
   }
   if (reportMissing) {
     logger.error(
-      "build script must export a Hook class, default class, or one @behavior3.build-decorated class"
+      "build script must export a BuildHook class, Hook class, default class, or one @behavior3.build-decorated class"
+    );
+  }
+  return void 0;
+};
+var createBatchHooks = (moduleExports, env, reportMissing = true) => {
+  if (!moduleExports || typeof moduleExports !== "object") {
+    return void 0;
+  }
+  const moduleRecord = moduleExports;
+  const defaultExport = isDecoratedCheckCtor(moduleRecord.default) || isDecoratedBuildHookCtor(moduleRecord.default) || isDecoratedBatchHookCtor(moduleRecord.default) ? void 0 : moduleRecord.default;
+  const ctor = moduleRecord.BatchHook ?? findDecoratedBatchHookCtor(moduleRecord) ?? moduleRecord.Hook ?? defaultExport;
+  if (typeof ctor === "function") {
+    try {
+      const instance = new ctor(env);
+      if (hasBuildHookMethod(instance) || typeof instance.shouldUpgradeTree === "function") {
+        return instance;
+      }
+      logger.error("batch hook class instance has no supported hook methods");
+    } catch (error) {
+      logger.error("failed to instantiate batch hook class", error);
+    }
+  }
+  if (reportMissing) {
+    logger.error(
+      "batch script must export a BatchHook class, default class, or one @behavior3.batch-decorated class"
     );
   }
   return void 0;
@@ -213462,13 +213518,13 @@ var createBuildScriptRuntime = (moduleExports, env) => {
     };
   }
   const moduleRecord = moduleExports;
-  const hasBuildHookCandidate = typeof moduleRecord.Hook === "function" || Object.values(moduleRecord).some(isDecoratedHookCtor) || typeof moduleRecord.default === "function" && !isDecoratedCheckCtor(moduleRecord.default);
-  const buildScript = createBatchHooks(moduleExports, env, false);
+  const hasBuildHookCandidate = typeof moduleRecord.BuildHook === "function" || typeof moduleRecord.Hook === "function" || Object.values(moduleRecord).some(isDecoratedBuildHookCtor) || typeof moduleRecord.default === "function" && !isDecoratedCheckCtor(moduleRecord.default) && !isDecoratedBatchHookCtor(moduleRecord.default);
+  const buildScript = createBuildHooks(moduleExports, env, false);
   const checkerResult = createNodeArgCheckers(moduleExports, env);
   const hasEntries = Boolean(buildScript) || checkerResult.hasCheckers;
   if (!hasEntries) {
     logger.error(
-      "build script must export a Hook class, default build class, @behavior3.build class, or @behavior3.check class"
+      "build script must export a BuildHook class, Hook class, default build class, @behavior3.build class, or @behavior3.check class"
     );
   }
   return {
@@ -213889,6 +213945,7 @@ var applyBehavior3DecoratorGlobal = () => {
   runtimeGlobal.behavior3 = {
     ...decoratorGlobalState.previousBehavior3 && typeof decoratorGlobalState.previousBehavior3 === "object" ? decoratorGlobalState.previousBehavior3 : {},
     build: markBuildHook,
+    batch: markBatchHook,
     check: markCheckHook
   };
 };
@@ -213909,7 +213966,7 @@ var restoreBehavior3DecoratorGlobal = () => {
   decoratorGlobalState.hadBehavior3 = false;
   decoratorGlobalState.previousBehavior3 = void 0;
 };
-var withBehavior3BuildDecoratorGlobal = async (loader) => {
+var withBehavior3ScriptDecoratorGlobal = async (loader) => {
   applyBehavior3DecoratorGlobal();
   try {
     return await loader();
@@ -214048,7 +214105,7 @@ var loadRuntimeModule = async (modulePath, options) => {
       }
     }
     if (getRuntimeProcess()?.type === "renderer") {
-      return await withBehavior3BuildDecoratorGlobal(
+      return await withBehavior3ScriptDecoratorGlobal(
         () => import(
           /* @vite-ignore */
           `${modulePath}?t=${Date.now()}`
@@ -214076,7 +214133,7 @@ var loadRuntimeModule = async (modulePath, options) => {
       return null;
     }
     const normalizedModulePath = b3path_default.posixPath(tempModulePath);
-    const result = await withBehavior3BuildDecoratorGlobal(
+    const result = await withBehavior3ScriptDecoratorGlobal(
       () => import(
         /* @vite-ignore */
         `file:///${normalizedModulePath}?t=${Date.now()}`