@bitakit/core 0.1.2 → 0.2.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 (157) hide show
  1. package/README.md +44 -207
  2. package/discovery/index.d.ts +1 -41
  3. package/discovery/index.mjs +1 -4
  4. package/dist/actions/action-list.d.ts +4 -0
  5. package/dist/actions/action-list.js +58 -16
  6. package/dist/actions/action.d.ts +2 -0
  7. package/dist/actions/action.js +4 -0
  8. package/dist/actions/brand.d.ts +21 -0
  9. package/dist/actions/brand.js +36 -0
  10. package/dist/actions/core.d.ts +4 -3
  11. package/dist/actions/core.js +4 -2
  12. package/dist/actions/execution.d.ts +2 -2
  13. package/dist/actions/execution.js +61 -9
  14. package/dist/actions/feedback.d.ts +2 -0
  15. package/dist/actions/feedback.js +8 -0
  16. package/dist/actions/groups.js +5 -1
  17. package/dist/actions/instance-bindings.js +3 -2
  18. package/dist/actions/interceptors.d.ts +9 -3
  19. package/dist/actions/interceptors.js +31 -3
  20. package/dist/actions/navigation.d.ts +2 -1
  21. package/dist/actions/navigation.js +10 -5
  22. package/dist/actions/reference.js +10 -5
  23. package/dist/actions/types.d.ts +9 -1
  24. package/dist/app/access.d.ts +4 -4
  25. package/dist/app/access.js +33 -71
  26. package/dist/app/action-access.d.ts +2 -2
  27. package/dist/app/action-access.js +6 -4
  28. package/dist/app/service-error.d.ts +2 -2
  29. package/dist/app/service-error.js +10 -6
  30. package/dist/app/types.d.ts +76 -33
  31. package/dist/config-service.d.ts +30 -6
  32. package/dist/config-service.js +25 -9
  33. package/dist/configuration.d.ts +6 -3
  34. package/dist/configuration.js +8 -6
  35. package/dist/contracts.d.ts +4 -2
  36. package/dist/contracts.js +3 -3
  37. package/dist/contribution-origin.d.ts +4 -1
  38. package/dist/contribution-origin.js +14 -1
  39. package/dist/contributions/action.d.ts +26 -0
  40. package/dist/contributions/action.js +171 -0
  41. package/dist/contributions/host.d.ts +14 -11
  42. package/dist/contributions/index.d.ts +1 -26
  43. package/dist/contributions/index.js +1 -18
  44. package/dist/conventions.d.ts +8 -4
  45. package/dist/conventions.js +12 -31
  46. package/dist/core.d.ts +41 -18
  47. package/dist/core.js +25 -13
  48. package/dist/definitions.d.ts +272 -306
  49. package/dist/definitions.js +28 -56
  50. package/dist/destinations.d.ts +25 -0
  51. package/dist/destinations.js +21 -0
  52. package/dist/discovered.d.ts +52 -21
  53. package/dist/discovered.js +89 -35
  54. package/dist/events/define.d.ts +43 -0
  55. package/dist/events/define.js +17 -0
  56. package/dist/events/service.d.ts +35 -8
  57. package/dist/events/service.js +184 -42
  58. package/dist/events/types.d.ts +29 -9
  59. package/dist/inspection/inventory.d.ts +86 -0
  60. package/dist/inspection/inventory.js +132 -0
  61. package/dist/interceptors/define.d.ts +76 -0
  62. package/dist/interceptors/define.js +23 -0
  63. package/dist/interceptors/service-observers.d.ts +6 -3
  64. package/dist/interceptors/service-observers.js +13 -10
  65. package/dist/lifecycle/cleanup.d.ts +5 -0
  66. package/dist/lifecycle/cleanup.js +41 -0
  67. package/dist/lifecycle/controller.d.ts +82 -0
  68. package/dist/lifecycle/controller.js +276 -0
  69. package/dist/lifecycle/reconcile.d.ts +19 -0
  70. package/dist/lifecycle/reconcile.js +68 -0
  71. package/dist/lifecycle/state.d.ts +53 -0
  72. package/dist/lifecycle/state.js +86 -0
  73. package/dist/names.d.ts +10 -0
  74. package/dist/names.js +1 -0
  75. package/dist/pages.d.ts +39 -6
  76. package/dist/pages.js +93 -11
  77. package/dist/presentation.d.ts +9 -0
  78. package/dist/runtime.d.ts +166 -28
  79. package/dist/runtime.js +1485 -248
  80. package/dist/schema.d.ts +13 -0
  81. package/dist/schema.js +38 -0
  82. package/dist/scope.d.ts +59 -4
  83. package/dist/scope.js +133 -11
  84. package/dist/service-key.d.ts +33 -14
  85. package/dist/service-key.js +21 -5
  86. package/dist/service-names.d.ts +39 -0
  87. package/dist/service-names.js +175 -0
  88. package/dist/services.d.ts +24 -5
  89. package/dist/services.js +230 -37
  90. package/dist/settings/access.d.ts +19 -0
  91. package/dist/settings/access.js +78 -0
  92. package/dist/settings/define.d.ts +97 -0
  93. package/dist/settings/define.js +83 -0
  94. package/dist/settings/storage.d.ts +45 -0
  95. package/dist/settings/storage.js +102 -0
  96. package/dist/settings/store.d.ts +74 -0
  97. package/dist/settings/store.js +345 -0
  98. package/dist/slots/action-placement.d.ts +47 -0
  99. package/dist/slots/action-placement.js +1 -0
  100. package/dist/slots/define.d.ts +52 -0
  101. package/dist/slots/define.js +12 -0
  102. package/dist/slots/normalize.d.ts +7 -0
  103. package/dist/slots/normalize.js +36 -0
  104. package/dist/slots/runtime.d.ts +43 -0
  105. package/dist/slots/runtime.js +348 -0
  106. package/dist/slots/types.d.ts +113 -0
  107. package/dist/slots/types.js +1 -0
  108. package/dist/startup-error.d.ts +21 -0
  109. package/dist/startup-error.js +29 -0
  110. package/dist/store.d.ts +24 -0
  111. package/dist/store.js +40 -0
  112. package/dist/translation.d.ts +9 -4
  113. package/dist/translation.js +2 -3
  114. package/examples/todos/actions/create.mjs +1 -3
  115. package/examples/todos/actions/delete.mjs +3 -10
  116. package/examples/todos/actions/list.mjs +1 -3
  117. package/examples/todos/events.mjs +5 -0
  118. package/examples/todos/plugin.mjs +4 -2
  119. package/examples/todos/services/tasks.mjs +14 -20
  120. package/examples/todos.mjs +8 -7
  121. package/package.json +36 -9
  122. package/testing/index.d.ts +59 -0
  123. package/testing/index.mjs +150 -0
  124. package/assets/bitakit-banner.png +0 -0
  125. package/discovery/entries.mjs +0 -124
  126. package/discovery/generate.mjs +0 -321
  127. package/discovery/host.mjs +0 -12
  128. package/discovery/modules.mjs +0 -13
  129. package/discovery/packages.mjs +0 -57
  130. package/discovery/watch.mjs +0 -23
  131. package/dist/app/service-aliases.d.ts +0 -4
  132. package/dist/app/service-aliases.js +0 -14
  133. package/dist/contributions/command.d.ts +0 -8
  134. package/dist/contributions/command.js +0 -59
  135. package/dist/contributions/dialog.d.ts +0 -8
  136. package/dist/contributions/dialog.js +0 -18
  137. package/dist/contributions/form.d.ts +0 -10
  138. package/dist/contributions/form.js +0 -67
  139. package/dist/contributions/native.d.ts +0 -11
  140. package/dist/contributions/native.js +0 -87
  141. package/dist/contributions/shared.d.ts +0 -19
  142. package/dist/contributions/shared.js +0 -48
  143. package/dist/contributions/stateful-action.d.ts +0 -29
  144. package/dist/contributions/stateful-action.js +0 -33
  145. package/dist/events/action-setup.d.ts +0 -19
  146. package/dist/events/action-setup.js +0 -24
  147. package/dist/interceptors/service.d.ts +0 -37
  148. package/dist/interceptors/service.js +0 -7
  149. package/dist/replacements.d.ts +0 -22
  150. package/dist/replacements.js +0 -54
  151. package/dist/validation.d.ts +0 -2
  152. package/dist/validation.js +0 -16
  153. package/docs/auth.md +0 -106
  154. package/docs/events.md +0 -157
  155. package/docs/file-contributions.md +0 -174
  156. package/docs/reference.md +0 -404
  157. package/docs/todo-tutorial.md +0 -88
package/docs/events.md DELETED
@@ -1,157 +0,0 @@
1
- # Events and action setup
2
-
3
- Workspace API, pending publication. Core owns one mitt-backed event bus per
4
- `FoundationRuntime`, available as `runtime.events` and `app.events`. There is no
5
- global bus, React dependency, replay buffer, persistence, or cross-process delivery.
6
-
7
- ## Sending and receiving
8
-
9
- Service `create({ events })` and action `setup({ events, services, action, app, config })`
10
- receive scoped views of the same bus. Emit after the source data has changed:
11
-
12
- ```ts
13
- events.emit('todos.changed', { kind: 'added', id: 42 });
14
-
15
- events.watch(['todos.loaded', 'todos.changed'], (event, { signal }) => {
16
- console.log(event.type, event.data, signal.aborted);
17
- });
18
- ```
19
-
20
- Each event invokes the handler once, even if its name appears twice in the array.
21
- The array means OR, not waiting for all events or batching them. Names are literal;
22
- `*` is not a wildcard. Callbacks may emit further events synchronously, so applications
23
- must avoid event cycles.
24
-
25
- `watch` returns an idempotent function for optional early unsubscription. In action
26
- setup and service creation, ownership is automatic. Direct `app.events.watch` calls
27
- are caller-owned until runtime unmount; use the returned cleanup outside these scopes.
28
-
29
- ## Declarative Action events
30
-
31
- For a fixed set of custom events, declare one shared handler:
32
-
33
- ```ts
34
- export default defineAction({
35
- events: ['todos.changed', 'selection.changed'],
36
- onEvent(event, { services, action, signal }) {
37
- switch (event.type) {
38
- case 'todos.changed':
39
- action.enabled = services.todos.list().length > 0;
40
- break;
41
- case 'selection.changed':
42
- // Use event.data or call a feature-specific function.
43
- break;
44
- }
45
- },
46
- });
47
- ```
48
-
49
- The handler receives the same context as setup, plus the subscription's AbortSignal.
50
- It may be async. Subscriptions are installed before `setup` and share its owned
51
- scope, including rollback when setup fails. Declaring events does not synthesize
52
- an initial event, execute the Action, or automatically refresh all Actions. Use
53
- setup for an initial check; use onEvent for the reaction you actually need.
54
- Known payloads are inferred from the event names when defineAction's generics are
55
- inferred. Supplying explicit type arguments uses the default event-name type unless
56
- that parameter is also specified; events.watch can infer its names independently.
57
-
58
- For local form input, prefer the existing per-binding input rather than writing a
59
- shared enabled flag from text-change events:
60
-
61
- ```ts
62
- export default defineAction({
63
- resolve: (text: string) => ({ enabled: typeof text === 'string' && text.length > 0 }),
64
- execute: ({ input, services }) => services.todos.add(input),
65
- });
66
-
67
- // Inside the React form; text is the current form value.
68
- <ActionButton action="todos.add" input={text} />
69
- ```
70
-
71
- Each binding evaluates its own input. Two forms using the same Action can therefore
72
- have different enabled states. Mutating nested input fields in place is not observed;
73
- pass updated input values through the existing form/React state. A custom event
74
- that writes action.enabled instead changes the shared registration for all bindings.
75
-
76
- ## Action lifecycle
77
-
78
- `setup` runs synchronously once per registration, after the services exist. It can
79
- return a cleanup for other resources. Register async event handlers inside setup;
80
- do not make setup itself async. Public `app.services` becomes available only after
81
- runtime mount; setup uses its directly supplied `services` context.
82
-
83
- `action.enabled`, `visible`, `checked`, and other presentation properties write to
84
- the existing ActionList store. `action.get()` reads the current snapshot;
85
- `action.update(patch)` supports combined updates. There is no mirrored action store.
86
- Writes after removal are ignored, including writes from a previous registration
87
- after another action takes its ID.
88
-
89
- Run the initial check explicitly after subscribing. Events are notifications, not
90
- stored state. The service remains the source of truth. Existing `resolve(input, context)`
91
- can derive input-specific guards at execution time; changing `enabled` is only a
92
- presentation/global execution guard, not server authorization or input validation.
93
-
94
- Action removal, list disposal, runtime unmount, and failed setup release subscriptions.
95
- Service subscriptions follow service disposal. Runtime remount creates fresh owned
96
- subscriptions. A disposed scoped sender cannot emit into a later mount.
97
-
98
- Definition-level `watch: ['serviceId']` keeps its existing meaning: subscribe to an
99
- observable service and refresh presentation. `events.watch(...)` listens to named
100
- events; it does not reinterpret that older property.
101
-
102
- ## Async handlers and errors
103
-
104
- `emit` dispatches synchronously in registration order and returns `void`. An async
105
- handler starts immediately, but the emitter does not await its promise. Handlers
106
- can overlap; there is no serialization or latest-request-wins behavior.
107
-
108
- Both synchronous throws and promise rejections go to
109
- `FoundationConfig.onEventError(error, event)`. The default reports to `console.error`.
110
- One failing handler does not prevent other handlers from receiving the event.
111
- Errors are reported even if the handler rejects after unsubscription.
112
-
113
- Each subscription supplies an `AbortSignal`, aborted when unsubscribed. Pass it to
114
- abort-aware operations and check it before external side effects after `await`:
115
-
116
- ```ts
117
- events.watch('documents.reload', async (event, { signal }) => {
118
- const response = await fetch('/api/documents', { signal });
119
- const documents = await response.json();
120
- if (!signal.aborted) updateDocuments(documents);
121
- });
122
- ```
123
-
124
- Unsubscription cannot forcibly cancel arbitrary JavaScript or undo side effects.
125
- Applications decide how to handle expected cancellation in their handler/error reporter.
126
-
127
- ## Typed payloads
128
-
129
- Augment the shared event map for known names. This does not register anything at runtime:
130
-
131
- ```ts
132
- declare module '@bitakit/core' {
133
- interface EventMap {
134
- 'todos.changed': { kind: 'added' | 'removed'; id: number };
135
- 'todos.loaded': undefined;
136
- }
137
- }
138
- ```
139
-
140
- Known events require matching payloads. Multi-event handlers receive a discriminated
141
- `{ type, data }` union. Unknown names remain permitted with an `unknown` payload,
142
- so independently developed plugins can participate without a global registry.
143
-
144
- ## React
145
-
146
- ```ts
147
- import { useWatchEvent } from '@bitakit/ui';
148
-
149
- useWatchEvent(['todos.loaded', 'todos.changed'], (event) => {
150
- // React to event.type and event.data.
151
- });
152
- ```
153
-
154
- The hook subscribes once the Foundation runtime is ready, follows current callbacks,
155
- and unsubscribes when names/runtime change or the component unmounts. Inline name
156
- arrays do not resubscribe when their contents stay the same. Events emitted before
157
- the subscription are not replayed; read source state for initial rendering.
@@ -1,174 +0,0 @@
1
- # Dateibasierte Beiträge und Config
2
-
3
- ## Verbindlicher Stand
4
-
5
- Core erkennt Actions, Services, Interceptors und Config über dieselbe Dateipfad-Normalisierung. Die Node-Discovery generiert statische Imports; sie führt Beitragscode nicht aus. App-/Plugin-Manifeste und die Build-Konfiguration werden dagegen geladen und müssen vertrauenswürdig sein.
6
-
7
- ```text
8
- actions.refresh.ts = actions/refresh.ts
9
- services.logging.ts = services/logging.ts
10
- interceptors.log.ts = interceptors/log.ts
11
- configs.actions.refresh.ts = configs/actions/refresh.ts
12
- actions.documents.publish.ts = actions/documents/publish.ts
13
- = actions/documents.publish.ts
14
- ```
15
-
16
- Der erste Abschnitt bezeichnet die Beitragsart. Weitere Punkte und Ordner sind gleichwertige Pfadsegmente. `index.ts` bezeichnet die Sammlung am Elternpfad, etwa `actions/index.ts` = `actions.ts`. Bestehende Suffixe wie `refresh.action.ts`, `invite.form-action.ts` und `logging.service.ts` bleiben Migrationsaliase; `index.action.ts` bleibt ausdrücklich eine Action namens `index`.
17
-
18
- Nur TypeScript-/TSX-Dateien mit Default-Export werden importiert. Der TypeScript-Parser erkennt diese Exporte, ohne die Module auszuführen. Hilfsdateien ohne Default-Export sowie Pfadsegmente mit führendem `-` werden nicht registriert. `.d.ts` und `server`-Pfadsegmente sind ausgeschlossen. Diese Erkennung ersetzt keine Prüfung transitiver Imports durch das jeweilige Framework: Ein Client-Beitrag darf weiterhin keinen Server-Code importieren. Es gibt noch keine generische Server-Discovery.
19
-
20
- Each immediate folder under `src/plugins` defines a local plugin; `plugin.config.ts` is optional and overrides the inferred folder ID. Explicit nested plugin manifests retain their own boundaries. Symlinks are rejected. `foundation.config.ts` can customize the plugin root and explicit directories. Public service names use the relative service path or explicit ID, while internal service keys retain their module namespace.
21
-
22
- ## Modul und IDs
23
-
24
- ```ts
25
- // src/plugins/content/plugin.config.ts
26
- export default { id: 'content' };
27
- ```
28
-
29
- `actions.refresh.ts` erzeugt `content.refresh`; `services.logging.ts` erzeugt `content.logging`. Explizite Action-/Service-IDs bleiben vorrangig, insbesondere geteilte `serviceKey`-Verträge. Bei Services ohne explizite ID kann `defineService({ create })` verwendet werden. Manuelle Plugin-Registrierung benötigt weiterhin vollständige Service-Definitionen mit ID.
30
-
31
- Auch die App verwendet dieselben Beiträge unter `src` (änderbar mit `directory`). Mit `src/plugin.config.ts` und `{ id: 'app' }` entstehen IDs wie `app.refresh`. Ohne App-Manifest bleiben bestehende App-IDs ohne Präfix erhalten; ihr Config-Modul heißt intern `@foundation/app`. Das optionale App-Manifest legt derzeit die Modul-ID fest; Host-Auswahl und Verzeichnisse werden weiterhin in `foundation.config.ts` konfiguriert.
32
-
33
- Eine explizite Action-ID verändert nicht den entdeckten Config-Pfad. Bei manueller Registrierung ohne Discovery kann `configPath: ['refresh']` den lokalen Pfad vorgeben; andernfalls werden die Segmente der expliziten ID verwendet. Eine registrierte globale ID wird niemals zur nachträglichen Ermittlung eines Plugin-Präfixes zerlegt.
34
-
35
- ## Sammlung oder Einzeldateien
36
-
37
- ```ts
38
- // actions.ts
39
- export default {
40
- refresh: defineAction({ execute: () => 'refreshed' }),
41
- publish: defineAction({ execute: () => 'published' }),
42
- };
43
- ```
44
-
45
- Dies entspricht zwei Dateien `actions.refresh.ts` und `actions.publish.ts`. Verschachtelte Sammlungen sind erlaubt. Services verwenden Definitionen mit `create`, Interceptors `before` oder `create`. Ein direkt exportierter Interceptor-Handler wird als `before` normalisiert. Eine Action-Funktion bleibt entsprechend der bestehenden API eine Factory, die eine `Action`-Instanz zurückgibt; sie wird nicht als Execute-Handler interpretiert. Klassen bleiben `Action`-Unterklassen.
46
-
47
- Die Define-Helfer bleiben sinnvoll für Callback-Typen und besondere Action-Funktionen. Ein einfaches Action-Objekt mit `execute` wird auch ohne Helper normalisiert. Nicht jede Beitragsart unterstützt jede Exportform; reine Config-Klassen und Decorators sind noch nicht implementiert.
48
-
49
- Sammlungen und Einzeldateien dürfen unterschiedliche Einträge liefern. Doppelte logische Einträge sind Fehler, auch wenn die Schreibweisen verschieden sind. Fehler nennen die Quellen. Config-Teilbäume werden zusammengefügt; derselbe Blattwert oder ein Skalar anstelle eines Teilbaums darf nicht zweimal definiert werden. Absichtliche Overrides sind ein eigener Schritt.
50
-
51
- ## Konfiguration und Nutzung
52
-
53
- ```ts
54
- // configs.ts
55
- export default {
56
- pageSize: 20,
57
- actions: {
58
- refresh: { pageSize: 50 },
59
- publish: { pageSize: 5 },
60
- },
61
- };
62
- ```
63
-
64
- Alternativ enthalten `configs.actions.refresh.ts` und `configs.actions.publish.ts` die jeweiligen `{ pageSize }`-Objekte. `configs.ts` enthält dann nur den allgemeinen Wert. `configs.refresh.ts` ist ausdrücklich ein anderer Pfad: `refresh`, nicht `actions.refresh`.
65
-
66
- ```ts
67
- // actions.refresh.ts
68
- import { defineAction } from '@bitakit/core';
69
- export default defineAction({
70
- execute({ config }) {
71
- return {
72
- shared: config.plugin.get('pageSize', 20),
73
- own: config.action.get('pageSize', 50),
74
- };
75
- },
76
- });
77
-
78
- // services.logging.ts
79
- import { defineService } from '@bitakit/core';
80
- export default defineService({
81
- create({ config }) {
82
- const pageSize = config.plugin.get('pageSize', 20);
83
- return { pageSize };
84
- },
85
- });
86
- ```
87
-
88
- Der Plugin-Scope zeigt auf die aufgelöste Modul-Konfiguration. Der Action-Scope zeigt auf `actions.<lokaler Action-Pfad>` desselben Baums. Es gibt keinen impliziten Fallback zum allgemeinen Plugin-Wert und keinen globalen „current action“-Zustand. Beide Scopes werden auch an Action-Factories und Klassen-Konstruktoren über `ActionEnvironment` übergeben. Dienste erhalten den Plugin-Scope bei `create`. Config wird vor dem Erzeugen der Services aufgelöst.
89
-
90
- `get('actions.refresh')` kann einen kompletten Teilbaum liefern. Ein Segmentarray adressiert literal benannte Schlüssel. Standardmäßig ist ein unbekannter Zugriff `unknown`; ein Fallback liefert einen nutzbaren Typ, stellt aber keine Laufzeitvalidierung dar. Für eine ausdrücklich typisierte Sicht gibt es `ConfigScope<T>` beziehungsweise `runtime.configuration.plugin<T>(id)`.
91
-
92
- Discovery erzeugt `ConfigMap`, `ServiceMap` und `ActionMap` auch für Sammlungen. `runtime.configuration.plugin('content')` erhält dadurch den entdeckten Config-Typ. Die automatische Runtime-Zuordnung typisiert jedoch nicht magisch den Parameter einer frei exportierten Funktion. Hier weiterhin Helfer oder Annotationen verwenden. Klassen-/Factory-Action-IDs werden wie bisher nicht automatisch in die `ActionMap` aufgenommen.
93
-
94
- ## Overrides und optionale Schemas
95
-
96
- ```ts
97
- // foundation.config.ts (Build-Komposition)
98
- export default {
99
- configOverrides: {
100
- content: { actions: { refresh: { pageSize: 100 } } },
101
- },
102
- };
103
- ```
104
-
105
- Dasselbe Feld ist bei manueller `FoundationConfig` verfügbar. Objekte werden rekursiv überschrieben, Arrays ersetzt und `undefined` übernimmt den Default. `null` ist ein ausdrücklicher Wert. Nur Config-Overrides, nicht doppelte Quelldefinitionen, verwenden diese Regel. Unbekannte Modulnamen in Overrides werden abgewiesen. Discovery und `resolveFoundationConfig` entfernen Overrides bekannter deaktivierter beziehungsweise abgewählter Plugins zusammen mit deren Beiträgen.
106
-
107
- ```ts
108
- // configs.actions.refresh.ts
109
- import { defineConfig } from '@bitakit/core';
110
- import { z } from 'zod';
111
-
112
- export default defineConfig({
113
- schema: z.object({ pageSize: z.number().int().positive().default(50) }),
114
- });
115
- ```
116
-
117
- Schema-Bibliotheken bleiben optional beim Verbraucher. Core akzeptiert einen synchronen `parse(unknown)`-Vertrag und ruft ihn auf den zusammengeführten Werten auf. Eine Root-Schema-Definition muss die vollständige Config besitzen; sie wird nicht zusätzlich mit Config-Dateien zusammengesetzt. Alternativ können einzelne Teilbäume eigene Schemas tragen. Ein Validierungsfehler verhindert Service-Erstellung und Action-Registrierung.
118
-
119
- Config ist ein eingefrorener Snapshot pro Runtime, für Plain Objects, Arrays und primitive Werte. Keine Laufzeit-Schreib-API, keine automatische Service-Neuerstellung. Der React-Hook `usePluginConfig(moduleId, path[, fallback])` liest denselben Snapshot und erhält bei Austausch der Provider-Komposition einen neuen Stand; er verspricht keine Updates durch Mutation. Implizites `useConfig` ohne Modul-Kontext wird noch nicht angeboten. Bestätigte Benutzerpräferenzen gehören weiter zu `AppPreferences`.
120
-
121
- ## Interceptors
122
-
123
- Plugin-Interceptors gelten standardmäßig nur für registrierte Actions ihres Plugins, einschließlich interner Formular-Submits. `scope: 'global'` erweitert dies ausdrücklich. Host-Interceptors bleiben aus Kompatibilitätsgründen standardmäßig global; `scope: 'plugin'` begrenzt sie auf das App-Modul. `before` bekommt den Config-Scope der ausgeführten Action. Factory-`create` bekommt den Scope des besitzenden Moduls.
124
-
125
- `order` sortiert aufsteigend; Gleichstände behalten die Registrierungsreihenfolge. Fachlich notwendige Reihenfolgen ausdrücklich angeben. App-Discovery aktiviert ohne `interceptors.enabled` alle erkannten Interceptors; ein angegebenes Array wählt sie ausdrücklich aus, `[]` deaktiviert sie. Vorhandene Listen bleiben erhalten. React-Provider werden weiterhin über eine explizite `enabled`-Liste ausgewählt.
126
-
127
- ## Interne Erweiterungspunkte
128
-
129
- - `discovery/entries.mjs`: eine Dateierfassung, ein Pfad-Normalisierer, Default-Export-Erkennung für alle Arten.
130
- - `discovery/generate.mjs`: Komposition der Module und statische Imports/Typen.
131
- - `src/discovered.ts`: Sammlungen auflösen und in vorhandene Verträge normalisieren.
132
- - `src/config-service.ts`: Auflösung, optionale Schemas und unveränderliche Scopes.
133
- - `src/contributions`: bestehende Action-Adapter; sie erhalten den zugeordneten Config-Kontext ausdrücklich.
134
- - `src/runtime.ts`: Lebenszyklus und Integration, kein Dateiscanner.
135
-
136
- Für weitere Arten den Kind-Katalog, Normalisierung und Generierung erweitern, nicht erneut Dateien durchsuchen. Ein öffentliches dynamisches Adapter-Plugin-API ist noch nicht implementiert. Pages und Views verwenden dieselbe Pfaderkennung, behalten aber ihre bisherigen Einzeldefinitionen; Sammeldateien sind dafür noch nicht vorgesehen.
137
-
138
- Zurückgestellt: Decorators, YAML, Remote-Konfiguration, reaktive Config-Updates und automatische UI-Bindungen, Server-Discovery, sowie Co-Location wie `actions/publish/action.ts` plus `config.ts`. Unter der aktuellen Grammatik hätten diese Dateien gewöhnliche zusätzliche Pfadsegmente; sie sind keine Spezialkonvention.
139
-
140
- ## Prüfung und Migration
141
-
142
- `npm test --workspace @bitakit/core` prüft Runtime, Typverträge, Isolation, Config und die gemeinsame Discovery. Die Tests im Next-Paket prüfen weiterhin Generator- und Watcher-Integration. Vor der Migration vorhandene Hilfsdateien mit Default-Export aus Beitragsordnern verschieben oder mit `-` ausschließen. Alte Suffix-Dateien und neue äquivalente Pfade dürfen nicht gleichzeitig denselben Beitrag definieren. Automatisch erzeugte IDs ändern sich nur bei einer Änderung des logischen Pfads.
143
-
144
- ## Root application lifecycle
145
-
146
- The root application may declare dependencies and metadata in src/plugin.config.ts. Its discovered pages and views are rendered alongside plugin contributions. Root setup.ts participates in dependency ordering and reverse cleanup. The app is not listed as a removable plugin and does not require a nested plugins directory. Root page/view support is an optional runtime capability, not a recommendation to replace host routing. In Next.js, app-owned pages and layouts use src/app/**/page.tsx and layout.tsx. Only independent plugin pages use Discovery through the host catch-all; do not create root pages.*.tsx files for app routes.
147
-
148
- ## Direct configuration access
149
-
150
- `app.config.documents.editor.pageSize` reads the existing immutable module snapshot.
151
- A config file may export `defineConfig({ defaults: { pageSize: 20 } })` without a schema.
152
- Schemas remain optional. Scoped callback access and runtime.configuration are unchanged.
153
-
154
- ## Mixed interceptor collections
155
-
156
- `interceptors/` accepts Action and Service definitions in one default export, including named
157
- object collections and arrays. `interceptors/actions/save.ts` and
158
- `interceptors/actions.save.ts` have the same organizational path; it does not determine the kind.
159
- Use defineActionInterceptor or defineServiceInterceptor to set that discriminator automatically.
160
- The legacy defineInterceptor remains an Action definition. Service observers can select one method
161
- or all methods; see the Core README for lifecycle and observation boundaries.
162
-
163
- ## Inline service names
164
-
165
- `defineService({ exposeAs: 'clock', create: ... })` and
166
- `provideService(clockKey, { exposeAs: 'clock', create: ... })` expose the same container
167
- instance through `app.services.clock`. Omit `exposeAs` in ordinary discovered files:
168
- Core uses the explicit service ID or relative file path. An explicit name changes only
169
- the app facade, not the internal module-scoped key used by `requires` and factory contexts.
170
-
171
- Generated hosts carry this name on each service definition instead of emitting a separate
172
- `publicServices` map. Runtime name resolution and collision checks are shared with manual
173
- composition. Existing public mappings and `discoverPublicServices` remain compatible.
174
- Generated and manual plugin types infer inline names, including dotted namespaces.