@vgai/editor 0.4.0 → 0.4.1

package/template/src/tools/README.md

@@ -1,16 +1,151 @@
-# src/tools — project tools
-
-Editor dev/tuning panels live here: `<name>.tool.tsx` exporting
-`tool = defineTool({...})` plus a default React component — the editor
-discovers them automatically. Placements: `'document'` (opens as a center
-workspace document via the palette's `Open Tool: <title>` action —
-`example.tool.tsx`, the shipped worked example; `'dock'` is a deprecated
-alias), `'utility'` (a bottom utility tab for transient output), and
-`'inspector'` (⚙ section in the Inspector when its `match(node, adapter)`
-accepts the selection, e.g. `adapter.components?.list(node.id)` —
-`spin.tool.tsx`). Inside an inspector tool, `useSelection()` (from
-`@engine/react/use-selection`) returns the selected node, its attached
-components, and each component's own authored config, live. Build panels
-from `@editor/widgets` (the editor's own widget kit + tokens) so they look
-native. Editor-only: `npm run build` never bundles this folder — see
-`docs/DATA-TOOLS-DESIGN.md` §3–§4 in the engine checkout.
+# src/tools — registered project callables
+
+A tool is an ordinary JavaScript/TypeScript function explicitly registered in
+`package.json#vgai.tools`. The callable module exports `tool = defineTool(...)`
+from `@vgai/sdk/tools`; keep reusable behavior in an ordinary sibling module so
+game code and npm scripts can call it directly.
+
+Every registered tool is discoverable and callable through:
+
+- `import { tools } from '@vgai/live'` → `tools.list()` / `tools.call(...)`
+- `vgai run --list` / `vgai run <name>`
+- the editor's Project Tools catalog and schema-driven fallback form
+
+A registration may also list editor `contributions`. Each one names an ordinary
+React module, a stable contribution point, and a title. Its default component
+receives `{ tool, client }` and calls `client.runProjectTool(tool.name, ...)`;
+it must not contain a second copy of the tool's behavior. The supported points
+are `workspace.document`, `workspace.utility`, and `selection.inspector` (the
+last also exports `match(node, adapter)`). Prefer a focused custom contribution
+for a substantial workflow; the generated form and Advanced JSON remain the
+universal fallback.
+
+Contribution UI is editor chrome. Use ordinary React for layout and state, and
+import shared interactive controls from `@editor/widgets` so buttons, fields,
+menus, focus rings, disabled states, density, and theme switching match the
+rest of the editor. Inline styles are appropriate for layout and data-driven
+values, not for forking the editor's control paint.
+
+Match the contribution point's native shape: documents can use a bounded,
+scrollable workspace; inspector sections should be dense and one-column;
+utilities should be compact rows or small status blocks rather than document
+forms dropped into the bottom dock. Keep badges to short statuses or counts.
+Buttons and badges are intrinsically sized; set `width: '100%'` only when a
+full-width action is intentional.
+
+```tsx
+import { Button, TextInput } from '@editor/widgets';
+```
+
+```json
+{
+  "entry": "./src/tools/tuning.tool.ts",
+  "contributions": [
+    {
+      "id": "tuning",
+      "point": "workspace.document",
+      "title": "Tuning",
+      "entry": "./src/tools/tuning.document.tsx"
+    }
+  ]
+}
+```
+
+The starter registers `project.tuning` and `project.autoplay`. Both callable
+implementations deliberately report `TOOL_NOT_CONFIGURED` until replaced with
+game-specific behavior. `npm run playtest` calls the same `runAutoplay`
+function as the registered autoplay tool.
+
+Installed libraries can advertise helper tools through their own
+`package.json#vgai.tools`; the humanoid bake is one example. Registration adds
+addressability only—there is no extension base class, tool lifecycle, scripting
+language, or domain switch in the host.
+
+## Provider-native generated asset
+
+Install Fal only in a project that authors Fal-backed assets:
+
+```sh
+npm install --save-dev @fal-ai/client@1.10.1 @vgai/fal-client-compat
+```
+
+Keep the useful implementation as ordinary code. This mock-first example uses
+the upstream Fal call unchanged, validates the PNG, and hands the accepted file
+to the host once. Direct and managed execution replace only the client Fetch
+configuration; they do not change `fal.run(...)` or add provenance bookkeeping.
+
+```ts
+// src/tools/generate-icon.ts
+import { createFalClient } from '@fal-ai/client';
+import { createMockFalFetch } from '@vgai/fal-client-compat/mock';
+import type { ToolContext } from '@vgai/sdk/tools';
+
+export interface GenerateIconInput {
+  prompt: string;
+}
+
+export async function generateIcon(input: GenerateIconInput, ctx: ToolContext) {
+  if (!ctx.projectOutputs) throw new Error('The project-output writer is unavailable.');
+  const fal = createFalClient({
+    credentials: 'vgai-mock',
+    fetch: createMockFalFetch(),
+  });
+  const generated = await fal.run('fal-ai/nano-banana', {
+    input: { prompt: input.prompt, output_format: 'png' },
+  });
+  const file = generated.data.images[0];
+  if (!file) throw new Error('Fal returned no image.');
+  const response = await fetch(file.url);
+  if (!response.ok) throw new Error(`Fal image download failed: HTTP ${response.status}.`);
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  const png = [137, 80, 78, 71, 13, 10, 26, 10];
+  if (!png.every((byte, index) => bytes[index] === byte)) {
+    throw new Error('Fal output is not a PNG.');
+  }
+  const path = 'public/generated/icon.png';
+  const committed = await ctx.projectOutputs.write([
+    { path, content: bytes, mediaType: 'image/png', role: 'asset' },
+  ]);
+  return {
+    path,
+    bytes: bytes.byteLength,
+    provenanceOperationId: committed.provenanceOperationId!,
+  };
+}
+```
+
+The externally callable definition is deliberately thin:
+
+```ts
+// src/tools/generate-icon.tool.ts
+import { defineTool } from '@vgai/sdk/tools';
+import { z } from 'zod';
+import { generateIcon } from './generate-icon';
+
+export const tool = defineTool({
+  name: 'project.icon.generate',
+  summary: 'Generate a project icon with Fal.',
+  description: 'Runs the project-owned native Fal call and commits one validated PNG.',
+  input: z.object({ prompt: z.string().min(1) }),
+  result: z.object({
+    path: z.string(),
+    bytes: z.number().int().positive(),
+    provenanceOperationId: z.string(),
+  }),
+  errors: [],
+  requires: { project: true },
+  host: 'node',
+  mutates: true,
+  supportsDryRun: false,
+  longRunning: true,
+  permission: { risk: 'write', summary: 'Writes one generated PNG into this project.' },
+  impl: generateIcon,
+});
+```
+
+Register `"./src/tools/generate-icon.tool.ts"` in `package.json#vgai.tools`,
+then call it with a normal JSON input file:
+
+```sh
+npm run vgai -- run project.icon.generate --input generate-icon.input.json --yes
+```

package/template/src/tools/autoplay.tool.ts

@@ -0,0 +1,31 @@
+import { defineTool } from '@vgai/sdk/tools';
+import { z } from 'zod';
+import { runAutoplay } from './autoplay';
+
+export const tool = defineTool({
+  name: 'project.autoplay',
+  summary: 'Autoplay this game.',
+  description:
+    'Runs the game-authored @vgai/live interaction and acceptance loop. The starter implementation deliberately fails until the game has an honest playable path.',
+  input: z.object({}),
+  result: z.object({
+    passed: z.boolean(),
+    summary: z.string(),
+    artifacts: z.array(z.string()),
+  }),
+  errors: [
+    {
+      code: 'TOOL_NOT_CONFIGURED',
+      summary: 'The starter autoplay tool has not been implemented for this game.',
+    },
+  ],
+  requires: { project: true, editor: true, play: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  longRunning: true,
+  permission: { risk: 'read', summary: 'Drives and observes the running game.' },
+  async impl() {
+    return runAutoplay();
+  },
+});

package/template/src/tools/autoplay.ts

@@ -0,0 +1,15 @@
+import { ToolError } from '@vgai/sdk/tools';
+
+export interface AutoplayResult {
+  passed: boolean;
+  summary: string;
+  artifacts: string[];
+}
+
+/** Replace this stub with ordinary `@vgai/live` calls that drive and verify honest input. */
+export async function runAutoplay(): Promise<AutoplayResult> {
+  throw new ToolError(
+    'TOOL_NOT_CONFIGURED',
+    'project.autoplay is a deliberate starter stub. Implement the first honest player interaction with @vgai/live as soon as the game becomes playable.',
+  );
+}

package/template/src/tools/tuning.document.tsx

@@ -0,0 +1,107 @@
+import { Button } from '@editor/widgets';
+import type { ToolContributionProps } from '@vgai/editor-sdk/contributions';
+import { useState } from 'react';
+
+/**
+ * Starter document for the game-specific tuning tool. Keep this UI small and
+ * intentional: its only job is to collect useful inputs and call the tool.
+ */
+export default function TuningDocument({ tool, client }: ToolContributionProps) {
+  const [result, setResult] = useState<unknown>(null);
+  const [running, setRunning] = useState(false);
+
+  const verify = async () => {
+    setRunning(true);
+    try {
+      setResult(await client.runProjectTool(tool.name, {}, { confirm: true }));
+    } finally {
+      setRunning(false);
+    }
+  };
+
+  return (
+    <main
+      style={{
+        padding: 24,
+        fontFamily: 'var(--vgai-font-sans)',
+        maxWidth: 760,
+        margin: '0 auto',
+        color: 'inherit',
+      }}
+      data-testid="tuning-starter"
+    >
+      <section
+        style={{
+          overflow: 'hidden',
+          border: '1px solid var(--vgai-boundary-default)',
+          borderRadius: 'var(--vgai-radius-md)',
+          background: 'var(--vgai-surface-panel)',
+        }}
+      >
+        <div style={{ padding: '20px 22px' }}>
+          <div
+            style={{
+              color: 'var(--vgai-content-dim)',
+              fontSize: 11,
+              fontWeight: 700,
+              letterSpacing: '0.08em',
+              textTransform: 'uppercase',
+            }}
+          >
+            Starter contribution · not configured
+          </div>
+          <h2 style={{ margin: '7px 0 6px', fontSize: 20 }}>Game tuning</h2>
+          <p
+            style={{
+              margin: 0,
+              maxWidth: 620,
+              color: 'var(--vgai-content-muted)',
+              lineHeight: 1.55,
+            }}
+          >
+            Replace the schema in <code>tuning.tool.ts</code>, implement the data changes in{' '}
+            <code>tuning.ts</code>, then replace this starter with focused controls for the values
+            designers should change. Keep the behavior in the registered tool.
+          </p>
+        </div>
+        <footer
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            gap: 16,
+            padding: '12px 22px',
+            borderTop: '1px solid var(--vgai-boundary-default)',
+            background: 'var(--vgai-surface-chrome)',
+          }}
+        >
+          <span style={{ color: 'var(--vgai-content-dim)', fontSize: 12 }}>
+            Calls <code>{tool.name}</code>
+          </span>
+          <Button
+            variant="solid"
+            disabled={running}
+            aria-busy={running}
+            onClick={() => void verify()}
+          >
+            {running ? 'Checking…' : 'Check callable stub'}
+          </Button>
+        </footer>
+      </section>
+      {result !== null && (
+        <pre
+          style={{
+            marginTop: 12,
+            padding: 12,
+            overflow: 'auto',
+            border: '1px solid var(--vgai-boundary-default)',
+            borderRadius: 'var(--vgai-radius-sm)',
+            background: 'var(--vgai-surface-inset)',
+          }}
+        >
+          {JSON.stringify(result, null, 2)}
+        </pre>
+      )}
+    </main>
+  );
+}

package/template/src/tools/tuning.tool.ts

@@ -0,0 +1,24 @@
+import { defineTool } from '@vgai/sdk/tools';
+import { z } from 'zod';
+import { runTuning } from './tuning';
+
+export const tool = defineTool({
+  name: 'project.tuning',
+  summary: 'Tune this game.',
+  description:
+    'Starter contract for the game-specific tuning tool. Replace its schema and ordinary implementation before use.',
+  input: z.object({}),
+  result: z.object({ updated: z.array(z.string()) }),
+  errors: [
+    {
+      code: 'TOOL_NOT_CONFIGURED',
+      summary: 'The starter tuning tool has not been customized for this game.',
+    },
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: true,
+  supportsDryRun: false,
+  permission: { risk: 'write', summary: "Updates this project's game-specific tuning data." },
+  impl: runTuning,
+});

package/template/src/tools/tuning.ts

@@ -0,0 +1,9 @@
+import { ToolError } from '@vgai/sdk/tools';
+
+/** Replace this stub with ordinary project code that updates the game's real tuning data. */
+export async function runTuning(_input: Record<string, never>): Promise<{ updated: string[] }> {
+  throw new ToolError(
+    'TOOL_NOT_CONFIGURED',
+    'project.tuning is a deliberate starter stub. Define the game-specific input schema, update its real tuning data, and make the game consume those values before using this tool.',
+  );
+}

package/template/src/ui/Button.stories.tsx

@@ -2,7 +2,7 @@
  * Worked CSF example — C3 (spec §9, docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md
  * "Add CSF Discovery and Portable Story Mounting"). A conventional
  * `*.stories.tsx` file next to the component it documents, same "the file is
- * the document" doctrine `src/tools/example.tool.tsx` and `src/data/`'s
+ * the document" doctrine `src/tools/tuning.document.tsx` and `src/data/`'s
  * trio already follow in this project. In a React-root project, add
  * `parameters: { vgai: { root: '<root-id>' } }` to associate a CSF document;
  * the editor then shows it beneath that root in the main hierarchy and mounts

package/template/tests/acceptance/example.spec.ts

@@ -1,64 +1,9 @@
-/**
- * L2 — acceptance layer (`docs/ACCEPTANCE-DRIVER-SPEC.md` §2.3): the canonical
- * worked example. Run with `npm run test:acceptance` (`vgai probe`) — never
- * `npx playwright test` (see `@vgai/probe`'s PROBE_ENV_MISSING error). Drives
- * the template's shipped example component, `DataSpinner`
- * (`src/scripts/components/data-spinner.ts`).
- */
-
+/** Replace this bridge smoke test with game-specific honest-input acceptance specs. */
 import { expect, test } from '@vgai/probe';
 
-// The built-in providers every project gets for free, no game code required
-// (Layer A, Task 1.2) — a small parametrized loop over an array of cases,
-// rather than one test per case copy-pasted.
-const BUILT_IN_PROVIDERS = ['time', 'input.actions'];
-
-test('the debug bridge is alive before any game-specific state is asserted on', async ({
-  game,
-}) => {
-  // proves the whole pipe (page → bridge → fixture) before any game code —
-  // a one-shot read races cold boot (sim may not have ticked yet under load),
-  // so this is a waitFor like every other time-dependent read in this file.
-  await game.waitFor((s) => (s('time') as { tick: number }).tick > 0, { simSeconds: 10 });
-});
-
-for (const name of BUILT_IN_PROVIDERS) {
-  test(`built-in provider "${name}" is enumerated`, async ({ game }) => {
-    const providers = await game.providers();
-    expect(providers.map((p) => p.name)).toContain(name);
-  });
-}
-
-test('spinner: fixture reset + honest-input boost + observable state + events + screenshot', async ({
-  game,
-}) => {
-  // Self-degrading (gem-runner friction, #146 ledger): this test proves the
-  // TEMPLATE's shipped example component. The moment you replace the default
-  // scene with your own game — no Box, no DataSpinner — it skips with this
-  // message instead of failing your suite red. Replace it with specs for
-  // YOUR game's providers (and delete this one) as your first real spec.
-  const providerNames = (await game.providers()).map((p) => p.name);
-  test.skip(
-    !providerNames.includes('spinner'),
-    'the default scene\'s DataSpinner is gone (you replaced the scene — good); ' +
-      'replace this example spec with specs for your own game state',
-  );
-
-  // Fixture (declared cheat, D16): jump to a known lapsCompleted before
-  // proving anything — never a substitute for the honest-input path below.
-  await game.command('spinner.reset');
-
-  // Proof: drive the SAME action a human would (see
-  // public/inputmaps/default.inputmap.json's 'attack' binding) — DataSpinner
-  // reads it via ctx.input.isPressed, not a synthetic backdoor.
-  await game.input.hold('attack', { simSeconds: 4 });
-
-  await game.waitFor((s) => (s('spinner') as { lapsCompleted: number }).lapsCompleted >= 1, {
+test('the debug bridge is alive', async ({ game }) => {
+  await game.waitFor((state) => (state('time') as { tick: number }).tick > 0, {
     simSeconds: 10,
   });
-  // one-shot reads are fine once a waitFor has established the state
-  const spinner = (await game.state('spinner')) as { lapsCompleted: number };
-  expect(spinner.lapsCompleted).toBeGreaterThanOrEqual(1);
-  await game.events.expect(['spin-lap']);
-  await game.screenshot('after-boosted-spin');
+  expect((await game.providers()).map((provider) => provider.name)).toContain('input.actions');
 });

package/template/vgai.game.json

@@ -6,7 +6,7 @@
   "editorPort": 5173,
   "version": "0.1.0",
   "engine": {
-    "version": "0.4.0"
+    "version": "0.4.1"
   },
   "resolution": {
     "width": 1280,