narraleaf-studio 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +119 -95
  2. package/dist/_api.d.ts +11412 -1994
  3. package/dist/plugin.d.ts +37 -2
  4. package/dist/runtime.d.ts +11 -0
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,95 +1,119 @@
1
- # narraleaf-studio
2
-
3
- TypeScript declarations for the [NarraLeaf Studio](https://github.com/NarraLeaf/NarraLeaf-Studio)
4
- plugin API.
5
-
6
- This package contains **types only**. Studio itself supplies the implementation
7
- at load time through an import map — there is no runtime code here.
8
-
9
- ```bash
10
- yarn add -D narraleaf-studio
11
- ```
12
-
13
- ## Usage
14
-
15
- ```ts
16
- // Studio entry — runs in the editor
17
- import { definePlugin } from "narraleaf-studio/plugin";
18
-
19
- export default definePlugin({
20
- setup(app) {
21
- app.services.blueprintNodes.registerMany(myNodes());
22
- app.services.ui.notifications.info(`${app.manifest.name} loaded`);
23
- },
24
- });
25
- ```
26
-
27
- ```ts
28
- // Runtime entry — runs inside the game
29
- import { defineRuntimePlugin } from "narraleaf-studio/runtime";
30
-
31
- export default defineRuntimePlugin({
32
- setup(app) {
33
- app.game.blueprintNodes.registerMany(myNodes());
34
- },
35
- });
36
- ```
37
-
38
- | Subpath | Surface |
39
- | -------------------------- | ---------------------------------------------------------------- |
40
- | `narraleaf-studio/plugin` | Editor: `definePlugin`, `PluginApp`, `PluginServices`, `ui` |
41
- | `narraleaf-studio/runtime` | Game: `defineRuntimePlugin`, `RuntimePluginApp` |
42
-
43
- The two are physically isolated at runtime. Importing `narraleaf-studio/plugin`
44
- from a runtime entry throws — the runtime host has no Studio services.
45
-
46
- ## You must mark these external
47
-
48
- Both specifiers have to be `external` in your bundler. Studio resolves them (and
49
- `react`, `react-dom`) through an import map, so bundling them produces a second,
50
- broken React instance and a plugin that fails to load.
51
-
52
- ```js
53
- // esbuild
54
- external: [
55
- "narraleaf-studio/plugin",
56
- "narraleaf-studio/runtime",
57
- "react",
58
- "react-dom",
59
- "react-dom/client",
60
- "react/jsx-runtime",
61
- ]
62
- ```
63
-
64
- If you forget, this package's stub throws at import with a message saying so.
65
-
66
- ## How these types are produced
67
-
68
- Generated directly from Studio's source by `packages/plugin-types/build.mjs`,
69
- not written by hand:
70
-
71
- | Output | Generated from |
72
- | ----------------- | ---------------------------------------------------------------- |
73
- | `dist/plugin.d.ts` | `src/renderer/plugin/index.ts` |
74
- | `dist/runtime.d.ts` | `src/renderer/lib/ui-editor/runtime/plugins/runtimePluginApi.ts` |
75
-
76
- Only what those entry points explicitly export is public. The build fails if the
77
- generated declarations do not typecheck on their own, so a release cannot ship a
78
- bundle that does not compile.
79
-
80
- ## Versioning
81
-
82
- This package versions independently of Studio: it changes when the plugin API
83
- changes, which is far less often than the app ships. Studio does not yet enforce
84
- a compatibility range at install time, so treat a major bump as "recompile your
85
- plugin and check it still typechecks".
86
-
87
- ## Getting started
88
-
89
- See the plugin authoring guide in the
90
- [NarraLeaf/Plugins](https://github.com/NarraLeaf/Plugins) registry, which has a
91
- working starter template.
92
-
93
- ## License
94
-
95
- MPL-2.0
1
+ # narraleaf-studio
2
+
3
+ TypeScript declarations for the [NarraLeaf Studio](https://github.com/NarraLeaf/NarraLeaf-Studio)
4
+ plugin API.
5
+
6
+ This package contains **types only**. Studio itself supplies the implementation
7
+ at load time through an import map — there is no runtime code here.
8
+
9
+ ```bash
10
+ yarn add -D narraleaf-studio
11
+ ```
12
+
13
+ ## Usage
14
+
15
+ ```ts
16
+ // Studio entry — runs in the editor
17
+ import { definePlugin } from "narraleaf-studio/plugin";
18
+
19
+ export default definePlugin({
20
+ setup(app) {
21
+ app.services.blueprintNodes.registerMany(myNodes());
22
+ app.services.ui.notifications.info(`${app.manifest.name} loaded`);
23
+ },
24
+ });
25
+ ```
26
+
27
+ ```ts
28
+ // Runtime entry — runs inside the game
29
+ import { defineRuntimePlugin } from "narraleaf-studio/runtime";
30
+
31
+ export default defineRuntimePlugin({
32
+ setup(app) {
33
+ app.game.blueprintNodes.registerMany(myNodes());
34
+ },
35
+ });
36
+ ```
37
+
38
+ | Subpath | Surface |
39
+ | -------------------------- | ---------------------------------------------------------------- |
40
+ | `narraleaf-studio/plugin` | Editor: `definePlugin`, `PluginApp`, `PluginServices`, `ui` |
41
+ | `narraleaf-studio/runtime` | Game: `defineRuntimePlugin`, `RuntimePluginApp` |
42
+
43
+ The two are physically isolated at runtime. Importing `narraleaf-studio/plugin`
44
+ from a runtime entry throws — the runtime host has no Studio services.
45
+
46
+ ## Tests
47
+
48
+ `narraleaf-studio/plugin` also carries the **test protocol** (`TestDefinition` and
49
+ everything it references, plus `TEST_PROTOCOL_VERSION`): checks an author runs
50
+ against their own game from Studio's Run ▸ Test, contributed through
51
+ `app.services.tests`. Nothing to do with your plugin's own unit tests.
52
+
53
+ ```ts
54
+ app.services.tests.register({
55
+ id: "acme.qa-pack.scene-names", // declare it in contributes.tests
56
+ title: { text: "Scenes are named" },
57
+ presentation: "headless",
58
+ requires: ["project.read"],
59
+ async run(ctx) { /* … */ return { status: "passed" }; },
60
+ });
61
+ ```
62
+
63
+ The contract — declaration, capabilities, who may claim which verdict, the
64
+ game-session lifecycle — is
65
+ [`docs/plugin-test-protocol.md`](https://github.com/NarraLeaf/NarraLeaf-Studio/blob/master/docs/plugin-test-protocol.md).
66
+
67
+ `TEST_PROTOCOL_VERSION` is a compile-time constant; import it with `import type`
68
+ and read the host's own version from `app.services.tests.protocolVersion`.
69
+
70
+ ## You must mark these external
71
+
72
+ Both specifiers have to be `external` in your bundler. Studio resolves them (and
73
+ `react`, `react-dom`) through an import map, so bundling them produces a second,
74
+ broken React instance and a plugin that fails to load.
75
+
76
+ ```js
77
+ // esbuild
78
+ external: [
79
+ "narraleaf-studio/plugin",
80
+ "narraleaf-studio/runtime",
81
+ "react",
82
+ "react-dom",
83
+ "react-dom/client",
84
+ "react/jsx-runtime",
85
+ ]
86
+ ```
87
+
88
+ If you forget, this package's stub throws at import with a message saying so.
89
+
90
+ ## How these types are produced
91
+
92
+ Generated directly from Studio's source by `packages/plugin-types/build.mjs`,
93
+ not written by hand:
94
+
95
+ | Output | Generated from |
96
+ | ----------------- | ---------------------------------------------------------------- |
97
+ | `dist/plugin.d.ts` | `src/renderer/plugin/index.ts` |
98
+ | `dist/runtime.d.ts` | `src/renderer/lib/ui-editor/runtime/plugins/runtimePluginApi.ts` |
99
+
100
+ Only what those entry points explicitly export is public. The build fails if the
101
+ generated declarations do not typecheck on their own, so a release cannot ship a
102
+ bundle that does not compile.
103
+
104
+ ## Versioning
105
+
106
+ This package versions independently of Studio: it changes when the plugin API
107
+ changes, which is far less often than the app ships. Studio does not yet enforce
108
+ a compatibility range at install time, so treat a major bump as "recompile your
109
+ plugin and check it still typechecks".
110
+
111
+ ## Getting started
112
+
113
+ See the plugin authoring guide in the
114
+ [NarraLeaf/Plugins](https://github.com/NarraLeaf/Plugins) registry, which has a
115
+ working starter template.
116
+
117
+ ## License
118
+
119
+ MPL-2.0