narraleaf-studio 0.9.0 → 1.0.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 (3) hide show
  1. package/README.md +119 -119
  2. package/dist/_api.d.ts +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,119 +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
- ## 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
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
package/dist/_api.d.ts CHANGED
@@ -15047,7 +15047,7 @@ type Messages = typeof en;
15047
15047
  type Flatten<T, Prefix extends string = ""> = {
15048
15048
  [K in keyof T & string]: T[K] extends string ? `${Prefix}${K}` : Flatten<T[K], `${Prefix}${K}.`>;
15049
15049
  }[keyof T & string];
15050
- type TranslationKey = Flatten<Messages>;
15050
+ type TranslationKey = Flatten<Messages> | (string & {});
15051
15051
  type PrivilegedWriteBatchEntry = {
15052
15052
  path: string;
15053
15053
  encoding?: FsTextEncoding;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "narraleaf-studio",
3
- "version": "0.9.0",
3
+ "version": "1.0.0",
4
4
  "description": "TypeScript declarations for the NarraLeaf Studio plugin API (narraleaf-studio/plugin and narraleaf-studio/runtime).",
5
5
  "license": "MPL-2.0",
6
6
  "type": "module",