@runic-artifex/svelte 0.4.0-preview.1 → 0.5.0-preview.3

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.
package/README.md CHANGED
@@ -1,262 +1,19 @@
1
1
  # `@runic-artifex/svelte`
2
2
 
3
- Make one Runic Toolkit Application Bridge controller feel native in a Svelte 5
4
- application. This package owns Svelte lifecycle, context, and rune projection
5
- while the controller remains authoritative for its snapshots, transport,
6
- commands, reconnect, and events.
3
+ Svelte 5 helpers for Runic Translations, inline content, and Application Views.
7
4
 
8
- ## Install
9
-
10
- ```sh
11
- npm install @runic-artifex/application-bridge@preview @runic-artifex/svelte@preview
12
- ```
13
-
14
- `@runic-artifex/svelte` is a public npm preview. The `preview` tag follows the
15
- current preview release without pinning a stale version.
16
-
17
- | Requirement | Supported range |
18
- |---|---|
19
- | Svelte | `>=5.46.4 <6` |
20
- | Effect | `4.0.0-rc.112` |
21
- | Runic Toolkit Application Bridge | `>=0.1.0-preview.30.1 <1` (optional peer; required by the root and `/bridge` entries) |
22
- | Runic Vite integration | `>=0.2.0-preview.1 <1` (optional peer; required only by `/vite`) |
23
-
24
- Svelte 4 and legacy stores are not supported.
25
-
26
- ### Public contract boundary
27
-
28
- This adapter follows the released Application Bridge controller: failures are
29
- the generated `BridgeError` union and Effect programs use its owned service.
30
- It does not retain adapter-local failure or runtime generics. The released
31
- local host boundary is the structural Application Bridge `FrameChannel`
32
- contract; Svelte neither creates a frame channel nor owns transport,
33
- reconnect, protocol, revision, or controller lifetime. The optional `/vite`
34
- entry covers the released Vite resource lifecycle; authentication, remote
35
- service transport, deployment, SSR, hydration, and rollout remain outside this
36
- adapter.
37
-
38
- ## Use an Application Bridge in Svelte 5
39
-
40
- `@runic-artifex/svelte/translations` is deliberately independent of the
41
- Application Bridge peer, so translation-only apps can install and render it
42
- without a bridge package. The package root and the additive
43
- `@runic-artifex/svelte/bridge` entry point load bridge support; if the optional
44
- peer is absent, they report the exact `npm install
45
- @runic-artifex/application-bridge@preview` remediation.
46
-
47
- Use `@runic-artifex/svelte/vite` only when registering Runic Vite
48
- DevTools. It supplies the bounded diagnostic observer and HMR resource helpers without
49
- making the root bridge entry depend on Vite.
50
-
51
- Create the controller with `@runic-artifex/application-bridge`, then create one
52
- Svelte projection and one typed context for the component tree. `provide()`
53
- starts the bridge after the first browser mount by default; it initializes the
54
- snapshot, then calls `uiReady()` and `uiRendered()`. It disposes the bridge on
55
- unmount by default.
56
-
57
- For a Runic Desktop application, compose the transport before constructing the
58
- Svelte projection. The generated contract is unchanged:
59
-
60
- ```ts
61
- import { createDesktopFrameChannel } from "@runic-artifex/desktop";
62
- import {
63
- ApplicationBridgeLive,
64
- createApplicationBridgeController,
65
- } from "@runic-artifex/application-bridge";
66
- import { SetupContract } from "./generated/setup-contract";
67
-
68
- export const controller = createApplicationBridgeController(
69
- SetupContract,
70
- ApplicationBridgeLive(SetupContract, createDesktopFrameChannel()),
71
- );
72
- ```
73
-
74
- The controller's Effect scope connects and closes the Desktop channel. Svelte
75
- mounting owns only its subscription and projection; dispose the controller once
76
- at the application-composition boundary after the Svelte root is unmounted.
77
-
78
- ```ts
79
- // src/lib/setup-bridge.svelte.ts
80
- import {
81
- createApplicationBridgeContext,
82
- createSvelteApplicationBridge,
83
- } from "@runic-artifex/svelte";
84
- import { controller } from "./setup-controller";
85
-
86
- export const setupBridge = createSvelteApplicationBridge(controller, {
87
- reduce: (snapshot, event) =>
88
- event._tag === "SnapshotReplaced" ? event.snapshot : snapshot,
89
- });
90
-
91
- export const setupBridgeContext = createApplicationBridgeContext();
92
- ```
93
-
94
- ```svelte
95
- <!-- src/routes/+page.svelte -->
96
- <script lang="ts">
97
- import { setupBridge, setupBridgeContext } from "$lib/setup-bridge.svelte";
98
-
99
- const bridge = setupBridgeContext.provide(setupBridge);
100
- let snapshot = $derived(bridge.snapshot);
101
-
102
- async function refresh() {
103
- await bridge.dispatch({ _tag: "Refresh" });
104
- }
105
- </script>
106
-
107
- <p>{bridge.status}</p>
108
- {#if snapshot}
109
- <button onclick={refresh}>Refresh</button>
110
- {/if}
111
- ```
112
-
113
- Keep transient presentation state in Svelte. Supply `reduce` when bridge events
114
- produce a newer snapshot; otherwise the initial/reconnect snapshots remain the
115
- projection's state. Call `bridge.cancel(operationId)` to request an explicit
116
- backend operation cancellation. Disposing a component is not a cancellation
117
- command.
118
-
119
- ## Optional: Runic Translations
120
-
121
- The `@runic-artifex/svelte/translations` subpath adapts a generated Runic
122
- Translations `LocaleSource` without making the generated catalog a runtime
123
- dependency. Install and configure the Runic Translations Vite plugin that
124
- provides your `virtual:runic-translations/...` modules, then create one locale
125
- context and provide a source per browser root or SSR component tree.
5
+ For locale context in a Svelte tree:
126
6
 
127
7
  ```ts
128
- // src/lib/locale-context.svelte.ts
129
8
  import { createLocaleContext } from "@runic-artifex/svelte/translations";
130
-
131
- export const localeContext = createLocaleContext<"en" | "de">();
132
9
  ```
133
10
 
134
- ```svelte
135
- <script lang="ts">
136
- import { createLocaleSource } from "virtual:runic-translations/app/runtime";
137
- import { localeContext } from "$lib/locale-context.svelte";
138
-
139
- let { data, children } = $props();
140
- const source = createLocaleSource({ initialLocale: data.locale });
141
- const locale = localeContext.provide(source);
142
- </script>
143
-
144
- <button onclick={() => locale.setLocale("de")}>Deutsch</button>
145
- {@render children()}
146
- ```
147
-
148
- A mutable source is updated directly. If navigation or application settings are
149
- authoritative, pass `requestLocale` to `provide()` and update the source through
150
- that callback. Initialize the client source from the root server load for
151
- deterministic hydration. For URL routing, use
152
- [`@runic-artifex/sveltekit/translations`](https://www.npmjs.com/package/@runic-artifex/sveltekit).
153
-
154
- ### Localization and visual-accessibility regression cases
155
-
156
- `@runic-artifex/svelte/translations/testing` provides framework-neutral data
157
- for a UI regression matrix. Mount each `localizationStressCases` entry with its
158
- `localizationStressAttributes`, render every `pluralStressCounts` value, and
159
- exercise each `visualAccessibilityStressScenarios` media query in the
160
- application's own browser harness. The fixtures include an expanded pseudo
161
- locale, an RTL string with a bidi-isolated identifier, and explicit forced
162
- colors, high-contrast, and reduced-motion checks. They deliberately do not
163
- prescribe application styling or replace real localized content.
164
-
165
- ```ts
166
- import {
167
- localizationStressCases,
168
- pluralStressCounts,
169
- visualAccessibilityStressScenarios,
170
- } from "@runic-artifex/svelte/translations/testing";
171
-
172
- for (const stressCase of localizationStressCases) {
173
- // Mount this exact text in your app's visual test with lang/dir attributes.
174
- }
175
-
176
- for (const count of pluralStressCounts) {
177
- // Render a real pluralized message for each count.
178
- }
179
- ```
180
-
181
- ## Hosted browser bootstrap
182
-
183
- For the hosted SSR profile, render the server-provided bootstrap fingerprint in
184
- `<meta name="runic-hosted-bootstrap">`, then call
185
- `startRunicHostedBridgeAfterBootstrap` inside `onMount`. A matching marker starts
186
- the supplied bridge; a mismatch records a fail-closed hydration state and leaves
187
- the bridge stopped. The marker guards render consistency only—it is not an
188
- authorization credential.
189
-
190
- ```svelte
191
- <script lang="ts">
192
- import { onMount } from "svelte";
193
- import { startRunicHostedBridgeAfterBootstrap } from "@runic-artifex/svelte/hosted";
194
-
195
- let { data, bridge } = $props();
196
-
197
- onMount(() => {
198
- if (!startRunicHostedBridgeAfterBootstrap(data.bootstrap, bridge)) return;
199
- return () => { void bridge.dispose(); };
200
- });
201
- </script>
202
-
203
- <svelte:head>
204
- <meta name="runic-hosted-bootstrap" content={data.bootstrap.fingerprint} />
205
- </svelte:head>
206
- ```
207
-
208
- This does not create a new transport or authorization path. The existing bridge
209
- remains controller-only; the W20 local FrameChannel/WebSocket boundary is not a
210
- hosted service route.
211
-
212
- ## Optional: Effect workflows
213
-
214
- If your controller exposes the Effect-aware Application Bridge contract, use
215
- `createEffectSvelteApplicationBridge`. It retains the ordinary Promise methods
216
- and exposes `effects`, `run`, `runExit`, and `createAction` over the controller's
217
- existing managed runtime—no renderer-owned Effect runtime is created.
218
-
219
- ```ts
220
- import { Effect } from "effect";
221
- import { createEffectSvelteApplicationBridge } from "@runic-artifex/svelte";
222
-
223
- const bridge = createEffectSvelteApplicationBridge(controller);
224
- const refresh = bridge.createAction((_input, effects) =>
225
- effects.dispatch({ _tag: "Refresh" }).pipe(Effect.asVoid),
226
- );
227
-
228
- void refresh.run(undefined);
229
- ```
230
-
231
- An action is latest-wins: beginning another invocation interrupts its preceding
232
- Fiber, and disposing the bridge interrupts its actions. That interruption only
233
- stops frontend work; use `cancel(operationId)` when the host operation itself
234
- must be cancelled.
235
-
236
- ## Links, status, and support
237
-
238
- - [Application Bridge guide](https://docs.runic-artifex.eu/application-bridge)
239
- - [Package catalog and release status](https://docs.runic-artifex.eu/packages)
240
- - [SvelteKit reference application](https://github.com/Runic-Artifex/runic-sdk/tree/main/apps/translations-editor/Frontend)
241
- - [Issues and support](https://github.com/Runic-Artifex/runic-sdk/issues)
242
- - [MIT License](https://github.com/Runic-Artifex/runic-sdk/blob/main/LICENSE)
243
-
244
- ## RMF2 inline content
245
-
246
- The optional `@runic-artifex/svelte/inline` entry point exports `inlineFactory`
247
- and `LocalizedInline`. Pass the factory to the catalog-generated
248
- `createInlineRenderer`, link custom contracts with `bindMarkup`, then supply its
249
- validated result to `<LocalizedInline nodes={nodes} custom={snippets} />`.
250
- Custom snippets are keyed by canonical names such as `shop:badge`. A custom
251
- binding can return its semantic node unchanged for the Svelte snippet to render.
252
-
253
- Use application-owned link/action/icon bindings from the generated runtime.
254
- Icons accept text or a Svelte snippet; meaningful icons need a localized
255
- accessible name. The adapter uses ordinary anchors and buttons, and leaves
256
- navigation and actions to those bindings. It never interprets localized text as
257
- HTML. Keep the linked renderer and slot bindings scoped to their application or
258
- request; SSR must not capture another request's callbacks.
11
+ The browser-safe `@runic-artifex/svelte/translations/testing` entry point
12
+ provides pseudo-localization, RTL isolation, plural boundary values, and
13
+ accessibility stress fixtures. `@runic-artifex/svelte/inline` exports
14
+ `LocalizedInline` and `inlineFactory` for localized structured content.
15
+ `@runic-artifex/svelte/views` exports `ViewOutlet`, `ViewReference`, and
16
+ `ViewRegistry` for generated Window/View clients.
259
17
 
260
- `bun run test:inline-browser` exercises SSR/hydration in the locked development
261
- shell's Chromium, including DOM identity, callback teardown, escaping and custom
262
- badge/icon semantics. The fixture is `test/InlineHydrationFixture.svelte`.
18
+ See the [Translations guide](https://github.com/Runic-Artifex/runic-sdk/tree/main/docs/guides/translations)
19
+ for catalog generation and the SvelteKit locale routing helpers.
package/dist/index.d.ts CHANGED
@@ -1,6 +1,2 @@
1
- export * from "./bridge.svelte.js";
2
- export * from "./context.svelte.js";
3
- export * from "./effect-action.svelte.js";
4
- export * from "./effect-bridge.svelte.js";
5
- export * from "./hosted.svelte.js";
6
- export * from "./types.js";
1
+ export * from "./translations/index.js";
2
+ export * from "./inline/index.js";
package/dist/index.js CHANGED
@@ -1,6 +1,2 @@
1
- export * from "./bridge.svelte.js";
2
- export * from "./context.svelte.js";
3
- export * from "./effect-action.svelte.js";
4
- export * from "./effect-bridge.svelte.js";
5
- export * from "./hosted.svelte.js";
6
- export * from "./types.js";
1
+ export * from "./translations/index.js";
2
+ export * from "./inline/index.js";
@@ -0,0 +1,16 @@
1
+ <script lang="ts">
2
+ import type { Component } from "svelte";
3
+ import type { ViewReference } from "./view-registry.js";
4
+
5
+ let { content, registry }: {
6
+ content: ViewReference | null | undefined;
7
+ registry: Readonly<Record<string, Component<{ page: any }>>>;
8
+ } = $props();
9
+ let Resolved = $derived(content ? registry[content.kind] : undefined);
10
+ </script>
11
+
12
+ {#if content && Resolved}
13
+ {#key content}<Resolved page={content} />{/key}
14
+ {:else if content}
15
+ <p role="alert">No web component is registered for {content.kind}.</p>
16
+ {/if}
@@ -0,0 +1,11 @@
1
+ import type { Component } from "svelte";
2
+ import type { ViewReference } from "./view-registry.js";
3
+ type $$ComponentProps = {
4
+ content: ViewReference | null | undefined;
5
+ registry: Readonly<Record<string, Component<{
6
+ page: any;
7
+ }>>>;
8
+ };
9
+ declare const ViewOutlet: Component<$$ComponentProps, {}, "">;
10
+ type ViewOutlet = ReturnType<typeof ViewOutlet>;
11
+ export default ViewOutlet;
@@ -0,0 +1,2 @@
1
+ export { default as ViewOutlet } from "./ViewOutlet.svelte";
2
+ export type { ViewReference, ViewRegistry } from "./view-registry.js";
@@ -0,0 +1 @@
1
+ export { default as ViewOutlet } from "./ViewOutlet.svelte";
@@ -0,0 +1,13 @@
1
+ import type { Component } from "svelte";
2
+ export interface ViewReference {
3
+ readonly kind: string;
4
+ connect(): Promise<unknown>;
5
+ }
6
+ /** Compile-time check that every View kind has a component with a matching page prop. */
7
+ export type ViewRegistry<R extends ViewReference> = {
8
+ readonly [K in R["kind"]]: Component<{
9
+ page: Extract<R, {
10
+ readonly kind: K;
11
+ }>;
12
+ }>;
13
+ };
package/package.json CHANGED
@@ -1,15 +1,14 @@
1
1
  {
2
2
  "name": "@runic-artifex/svelte",
3
- "version": "0.4.0-preview.1",
4
- "description": "Svelte 5 integration for the Runic Toolkit Application Bridge",
3
+ "version": "0.5.0-preview.3",
4
+ "description": "Svelte 5 localization and inline content helpers for Runic",
5
5
  "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/main/packages/web/svelte#readme",
6
6
  "bugs": {
7
7
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
8
8
  },
9
9
  "keywords": [
10
10
  "runic-artifex",
11
- "runic-toolkit",
12
- "application-bridge",
11
+ "translations",
13
12
  "svelte",
14
13
  "svelte-5"
15
14
  ],
@@ -32,24 +31,15 @@
32
31
  "types": "./dist/translations/testing.d.ts",
33
32
  "import": "./dist/translations/testing.js"
34
33
  },
35
- "./bridge": {
36
- "types": "./dist/bridge.svelte.d.ts",
37
- "svelte": "./dist/bridge.svelte.js",
38
- "import": "./dist/bridge.svelte.js"
39
- },
40
- "./hosted": {
41
- "types": "./dist/hosted.svelte.d.ts",
42
- "svelte": "./dist/hosted.svelte.js",
43
- "import": "./dist/hosted.svelte.js"
44
- },
45
- "./vite": {
46
- "types": "./dist/vite.d.ts",
47
- "import": "./dist/vite.js"
48
- },
49
34
  "./inline": {
50
35
  "types": "./dist/inline/index.d.ts",
51
36
  "svelte": "./dist/inline/index.js",
52
37
  "import": "./dist/inline/index.js"
38
+ },
39
+ "./views": {
40
+ "types": "./dist/views/index.d.ts",
41
+ "svelte": "./dist/views/index.js",
42
+ "import": "./dist/views/index.js"
53
43
  }
54
44
  },
55
45
  "files": [
@@ -60,24 +50,13 @@
60
50
  "scripts": {
61
51
  "build": "svelte-package -i src -o dist",
62
52
  "check": "svelte-check --tsconfig ./tsconfig.json",
63
- "test": "bun run --bun build && vitest run && node test/verify-inline-ssr.mjs",
53
+ "test": "bun run --bun build && vitest run test/locale.svelte.test.ts test/locale-hydration.svelte.test.ts test/localization-stress.test.ts && node test/verify-inline-ssr.mjs",
64
54
  "pack:check": "bun pm pack --dry-run",
65
55
  "test:inline-browser": "node test/verify-inline-ssr.mjs && node test/verify-inline-hydration.mjs"
66
56
  },
67
57
  "peerDependencies": {
68
- "@runic-artifex/application-bridge": "0.4.0-preview.1",
69
- "@runic-artifex/vite-plugin-runic": "0.4.0-preview.1",
70
- "effect": "4.0.0-rc.112",
71
58
  "svelte": ">=5.46.4 <6"
72
59
  },
73
- "peerDependenciesMeta": {
74
- "@runic-artifex/application-bridge": {
75
- "optional": true
76
- },
77
- "@runic-artifex/vite-plugin-runic": {
78
- "optional": true
79
- }
80
- },
81
60
  "publishConfig": {
82
61
  "access": "public",
83
62
  "tag": "preview"
@@ -92,14 +71,11 @@
92
71
  "node": ">=24.18.0 <25"
93
72
  },
94
73
  "devDependencies": {
95
- "@runic-artifex/application-bridge": "0.4.0-preview.1",
96
- "@runic-artifex/vite-plugin-runic": "0.4.0-preview.1",
97
74
  "@sveltejs/adapter-static": "3.0.10",
98
75
  "@sveltejs/kit": "2.70.3",
99
76
  "@sveltejs/package": "2.5.8",
100
77
  "@sveltejs/vite-plugin-svelte": "7.3.0",
101
78
  "@types/node": "24.13.3",
102
- "effect": "4.0.0-rc.112",
103
79
  "happy-dom": "^20.14.0",
104
80
  "svelte": "5.57.0",
105
81
  "svelte-check": "4.7.6",
@@ -107,5 +83,5 @@
107
83
  "vitest": "5.0.0",
108
84
  "vite": "8.2.2"
109
85
  },
110
- "gitHead": "25c8895a9a693da3d6e1a075c6bc503a56c26399"
86
+ "gitHead": "29265e112d21ee807f62327f42d61eb44d8dc5c8"
111
87
  }
@@ -1,18 +0,0 @@
1
- import type { ApplicationBridgeController, ApplicationBridgeStatus, SvelteApplicationBridgeOptions } from "./types.js";
2
- export declare class SvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot> {
3
- #private;
4
- snapshot: Snapshot | undefined;
5
- lastEvent: HostEvent | undefined;
6
- error: import("@runic-artifex/application-bridge").TransportUnavailable | import("@runic-artifex/application-bridge").TransportClosed | import("@runic-artifex/application-bridge").ProtocolVersionMismatch | import("@runic-artifex/application-bridge").ProtocolDecodeError | import("@runic-artifex/application-bridge").CommandRejected | import("@runic-artifex/application-bridge").StaleRevision | import("@runic-artifex/application-bridge").OperationFailed | import("@runic-artifex/application-bridge").OperationCancelled | import("@runic-artifex/application-bridge").OperationTimedOut | undefined;
7
- status: ApplicationBridgeStatus;
8
- constructor(controller: ApplicationBridgeController<Command, Receipt, HostEvent, Snapshot>, options?: SvelteApplicationBridgeOptions<HostEvent, Snapshot>);
9
- start(): Promise<Snapshot>;
10
- dispatch(command: Command): Promise<Receipt>;
11
- cancel(operationId: string): Promise<void>;
12
- reconnect(): Promise<Snapshot>;
13
- uiReady(): Promise<void>;
14
- uiRendered(): Promise<void>;
15
- clearError(): void;
16
- dispose(): Promise<void>;
17
- }
18
- export declare function createSvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot>(controller: ApplicationBridgeController<Command, Receipt, HostEvent, Snapshot>, options?: SvelteApplicationBridgeOptions<HostEvent, Snapshot>): SvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot>;
@@ -1,213 +0,0 @@
1
- // Keep the Application Bridge peer optional for translations-only applications,
2
- // while making bridge entry points fail with an actionable error when selected.
3
- await import("@runic-artifex/application-bridge").catch(() => {
4
- throw new Error("@runic-artifex/svelte bridge support requires @runic-artifex/application-bridge. "
5
- + "Install a compatible preview with `npm install @runic-artifex/application-bridge@preview`.");
6
- });
7
- export class SvelteApplicationBridge {
8
- snapshot = $state.raw(undefined);
9
- lastEvent = $state.raw(undefined);
10
- error = $state.raw(undefined);
11
- status = $state("idle");
12
- #controller;
13
- #reduce;
14
- #observer;
15
- #inspectSnapshot;
16
- #unsubscribe;
17
- #start;
18
- #dispose;
19
- #disposed = false;
20
- constructor(controller, options = {}) {
21
- this.#controller = controller;
22
- this.#reduce = options.reduce;
23
- this.#observer = options.observer;
24
- this.#inspectSnapshot = options.inspectSnapshot;
25
- }
26
- start() {
27
- if (this.#disposed)
28
- return Promise.reject(disposedError());
29
- if (this.#start)
30
- return this.#start;
31
- this.status = "connecting";
32
- this.error = undefined;
33
- this.#reportConnection("connecting");
34
- this.#unsubscribe ??= this.#controller.subscribe((event) => {
35
- if (this.#disposed)
36
- return;
37
- this.lastEvent = event;
38
- this.snapshot = this.#reduce?.(this.snapshot, event) ?? this.snapshot;
39
- this.#observer?.trace({ kind: "event", label: tagOf(event) });
40
- this.#reportConnection("connected");
41
- }, (failure) => {
42
- if (!this.#disposed)
43
- this.#fail(failure);
44
- });
45
- this.#start = this.#startController();
46
- return this.#start;
47
- }
48
- async dispatch(command) {
49
- this.#assertActive();
50
- this.#observer?.trace({ kind: "command", label: tagOf(command) });
51
- try {
52
- const receipt = await this.#controller.dispatch(command);
53
- this.#assertActive();
54
- this.#observer?.trace({ kind: "receipt", label: tagOf(receipt) });
55
- return receipt;
56
- }
57
- catch (failure) {
58
- if (this.#disposed)
59
- throw disposedError();
60
- this.#failUnknown(failure);
61
- throw failure;
62
- }
63
- }
64
- async cancel(operationId) {
65
- this.#assertActive();
66
- this.#observer?.trace({ kind: "operation", label: "CancelOperation", detail: { operationId } });
67
- try {
68
- await this.#controller.cancel(operationId);
69
- this.#assertActive();
70
- }
71
- catch (failure) {
72
- if (this.#disposed)
73
- throw disposedError();
74
- this.#failUnknown(failure);
75
- throw failure;
76
- }
77
- }
78
- async reconnect() {
79
- this.#assertActive();
80
- this.status = "reconnecting";
81
- this.error = undefined;
82
- this.#reportConnection("connecting");
83
- try {
84
- const snapshot = await this.#controller.reconnect();
85
- this.#assertActive();
86
- this.snapshot = snapshot;
87
- this.status = "connected";
88
- this.#reportSnapshot(snapshot, "connected");
89
- return snapshot;
90
- }
91
- catch (failure) {
92
- if (this.#disposed)
93
- throw disposedError();
94
- this.#failUnknown(failure);
95
- throw failure;
96
- }
97
- }
98
- async uiReady() {
99
- this.#assertActive();
100
- try {
101
- await this.#controller.uiReady();
102
- this.#assertActive();
103
- }
104
- catch (failure) {
105
- if (this.#disposed)
106
- throw disposedError();
107
- this.#failUnknown(failure);
108
- throw failure;
109
- }
110
- }
111
- async uiRendered() {
112
- this.#assertActive();
113
- try {
114
- await this.#controller.uiRendered();
115
- this.#assertActive();
116
- }
117
- catch (failure) {
118
- if (this.#disposed)
119
- throw disposedError();
120
- this.#failUnknown(failure);
121
- throw failure;
122
- }
123
- }
124
- clearError() {
125
- if (this.#disposed)
126
- return;
127
- this.error = undefined;
128
- if (this.status === "error")
129
- this.status = this.snapshot === undefined ? "idle" : "connected";
130
- }
131
- async dispose() {
132
- if (this.#dispose)
133
- return this.#dispose;
134
- this.#disposed = true;
135
- this.status = "disposed";
136
- this.#unsubscribe?.();
137
- this.#unsubscribe = undefined;
138
- this.#dispose = Promise.resolve()
139
- .finally(() => this.#reportConnection("closed"));
140
- return this.#dispose;
141
- }
142
- #fail(failure) {
143
- if (this.#disposed)
144
- return;
145
- this.error = failure;
146
- this.status = "error";
147
- this.#observer?.trace({ kind: "error", label: errorLabel(failure) });
148
- this.#reportConnection("disconnected");
149
- }
150
- #failUnknown(failure) {
151
- // Promise does not encode its rejection type; the controller contract does.
152
- this.#fail(failure);
153
- }
154
- async #startController() {
155
- try {
156
- const snapshot = await this.#controller.initialize();
157
- this.#assertActive();
158
- this.snapshot = snapshot;
159
- this.status = "connected";
160
- this.#reportSnapshot(snapshot, "connected");
161
- await this.#controller.uiReady();
162
- this.#assertActive();
163
- await this.#controller.uiRendered();
164
- this.#assertActive();
165
- this.#observer?.trace({ kind: "connection", label: "ui-rendered" });
166
- return snapshot;
167
- }
168
- catch (failure) {
169
- if (this.#disposed)
170
- throw disposedError();
171
- this.#start = undefined;
172
- this.#failUnknown(failure);
173
- throw failure;
174
- }
175
- }
176
- #assertActive() {
177
- if (this.#disposed)
178
- throw disposedError();
179
- }
180
- #reportSnapshot(snapshot, state) {
181
- const inspected = this.#inspectSnapshot?.(snapshot) ?? {};
182
- this.#observer?.state({
183
- connection: {
184
- state,
185
- transport: "application-bridge",
186
- ...inspected,
187
- },
188
- });
189
- }
190
- #reportConnection(state) {
191
- this.#observer?.state({ connection: { state, transport: "application-bridge" } });
192
- this.#observer?.trace({ kind: "connection", label: state });
193
- }
194
- }
195
- export function createSvelteApplicationBridge(controller, options = {}) {
196
- return new SvelteApplicationBridge(controller, options);
197
- }
198
- function tagOf(value) {
199
- if (typeof value === "object" && value !== null && "_tag" in value) {
200
- const tag = value._tag;
201
- if (typeof tag === "string" && tag.length > 0)
202
- return tag.slice(0, 128);
203
- }
204
- return "Unknown";
205
- }
206
- function errorLabel(failure) {
207
- if (typeof failure === "object" && failure !== null && "_tag" in failure)
208
- return tagOf(failure);
209
- return failure instanceof Error ? failure.name.slice(0, 128) : "ApplicationBridgeError";
210
- }
211
- function disposedError() {
212
- return new Error("The Svelte Application Bridge is disposed.");
213
- }
@@ -1,9 +0,0 @@
1
- import type { SvelteApplicationBridge } from "./bridge.svelte.js";
2
- export interface ApplicationBridgeContext<Command, Receipt, HostEvent, Snapshot> {
3
- provide(bridge: SvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot>, options?: Readonly<{
4
- start?: boolean;
5
- dispose?: boolean;
6
- }>): SvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot>;
7
- use(): SvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot>;
8
- }
9
- export declare function createApplicationBridgeContext<Command, Receipt, HostEvent, Snapshot>(): ApplicationBridgeContext<Command, Receipt, HostEvent, Snapshot>;
@@ -1,21 +0,0 @@
1
- import { createContext, onMount } from "svelte";
2
- export function createApplicationBridgeContext() {
3
- const [use, set] = createContext();
4
- return {
5
- provide(bridge, options = {}) {
6
- set(bridge);
7
- const shouldStart = options.start ?? true;
8
- const shouldDispose = options.dispose ?? true;
9
- onMount(() => {
10
- if (shouldStart)
11
- void bridge.start();
12
- return () => {
13
- if (shouldDispose)
14
- void bridge.dispose();
15
- };
16
- });
17
- return bridge;
18
- },
19
- use,
20
- };
21
- }
@@ -1,24 +0,0 @@
1
- import { Cause, Effect, Exit } from "effect";
2
- import type { ApplicationBridgeController, ApplicationBridgeService, EffectActionStatus } from "./types.js";
3
- type EffectRunner = Pick<ApplicationBridgeController<unknown, unknown, unknown, unknown>, "fork" | "await" | "interrupt">;
4
- /**
5
- * Projects one latest-wins Effect workflow into Svelte-native reactive state.
6
- * The supplied runner owns the Fiber; this class never creates an Effect runtime.
7
- */
8
- export declare class SvelteEffectAction<Input, Success, Failure> {
9
- #private;
10
- status: EffectActionStatus;
11
- value: Success | undefined;
12
- error: Failure | undefined;
13
- cause: Cause.Cause<Failure> | undefined;
14
- exit: Exit.Exit<Success, Failure> | undefined;
15
- constructor(runner: EffectRunner, program: (input: Input) => Effect.Effect<Success, Failure, ApplicationBridgeService>, onDispose?: () => void);
16
- get running(): boolean;
17
- /** Runs the workflow, interrupting an older invocation owned by this action. */
18
- run(input: Input): Promise<Exit.Exit<Success, Failure>>;
19
- /** Interrupts the current frontend workflow without implying backend cancellation. */
20
- interrupt(): Promise<Exit.Exit<Success, Failure> | undefined>;
21
- reset(): void;
22
- dispose(): Promise<void>;
23
- }
24
- export {};
@@ -1,99 +0,0 @@
1
- import { Cause, Effect, Exit, Option } from "effect";
2
- /**
3
- * Projects one latest-wins Effect workflow into Svelte-native reactive state.
4
- * The supplied runner owns the Fiber; this class never creates an Effect runtime.
5
- */
6
- export class SvelteEffectAction {
7
- status = $state("idle");
8
- value = $state.raw(undefined);
9
- error = $state.raw(undefined);
10
- cause = $state.raw(undefined);
11
- exit = $state.raw(undefined);
12
- #runner;
13
- #program;
14
- #onDispose;
15
- #fiber;
16
- #generation = 0;
17
- #disposed = false;
18
- constructor(runner, program, onDispose) {
19
- this.#runner = runner;
20
- this.#program = program;
21
- this.#onDispose = onDispose;
22
- }
23
- get running() {
24
- return this.status === "running";
25
- }
26
- /** Runs the workflow, interrupting an older invocation owned by this action. */
27
- async run(input) {
28
- if (this.#disposed)
29
- throw new Error("The Svelte Effect action is disposed.");
30
- const generation = ++this.#generation;
31
- const previous = this.#fiber;
32
- if (previous !== undefined)
33
- await this.#runner.interrupt(previous);
34
- if (this.#disposed || generation !== this.#generation) {
35
- throw new Error("The Svelte Effect action was disposed before it could start.");
36
- }
37
- this.status = "running";
38
- this.value = undefined;
39
- this.error = undefined;
40
- this.cause = undefined;
41
- this.exit = undefined;
42
- const fiber = this.#runner.fork(Effect.suspend(() => this.#program(input)));
43
- this.#fiber = fiber;
44
- const exit = await this.#runner.await(fiber);
45
- if (generation === this.#generation && !this.#disposed) {
46
- this.#fiber = undefined;
47
- this.#apply(exit);
48
- }
49
- return exit;
50
- }
51
- /** Interrupts the current frontend workflow without implying backend cancellation. */
52
- async interrupt() {
53
- if (this.#disposed)
54
- return undefined;
55
- const fiber = this.#fiber;
56
- if (fiber === undefined)
57
- return this.exit;
58
- ++this.#generation;
59
- this.#fiber = undefined;
60
- const exit = await this.#runner.interrupt(fiber);
61
- if (!this.#disposed)
62
- this.#apply(exit);
63
- return exit;
64
- }
65
- reset() {
66
- if (this.#disposed)
67
- throw new Error("The Svelte Effect action is disposed.");
68
- if (this.#fiber !== undefined)
69
- throw new Error("A running Svelte Effect action cannot be reset.");
70
- this.status = "idle";
71
- this.value = undefined;
72
- this.error = undefined;
73
- this.cause = undefined;
74
- this.exit = undefined;
75
- }
76
- async dispose() {
77
- if (this.#disposed)
78
- return;
79
- this.#disposed = true;
80
- ++this.#generation;
81
- const fiber = this.#fiber;
82
- this.#fiber = undefined;
83
- if (fiber !== undefined)
84
- await this.#runner.interrupt(fiber);
85
- this.status = "disposed";
86
- this.#onDispose?.();
87
- }
88
- #apply(exit) {
89
- this.exit = exit;
90
- if (Exit.isSuccess(exit)) {
91
- this.value = exit.value;
92
- this.status = "success";
93
- return;
94
- }
95
- this.cause = exit.cause;
96
- this.error = Option.getOrUndefined(Cause.findErrorOption(exit.cause));
97
- this.status = Cause.hasInterruptsOnly(exit.cause) ? "interrupted" : "failure";
98
- }
99
- }
@@ -1,19 +0,0 @@
1
- import type { Effect, Exit } from "effect";
2
- import { SvelteApplicationBridge } from "./bridge.svelte.js";
3
- import { SvelteEffectAction } from "./effect-action.svelte.js";
4
- import type { ApplicationBridgeController, ApplicationBridgeEffects, ApplicationBridgeService, SvelteApplicationBridgeOptions } from "./types.js";
5
- /** Opt-in Effect surface backed by the Application Bridge's owned runtime. */
6
- export declare class EffectSvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot> extends SvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot> {
7
- #private;
8
- readonly effects: ApplicationBridgeEffects<Command, Receipt, HostEvent, Snapshot>;
9
- constructor(controller: ApplicationBridgeController<Command, Receipt, HostEvent, Snapshot>, options?: SvelteApplicationBridgeOptions<HostEvent, Snapshot>);
10
- run<A, E>(program: Effect.Effect<A, E, ApplicationBridgeService>): Promise<A>;
11
- runExit<A, E>(program: Effect.Effect<A, E, ApplicationBridgeService>): Promise<Exit.Exit<A, E>>;
12
- /**
13
- * Creates a latest-wins action whose Fiber is interrupted when superseded or
14
- * when this application bridge is disposed.
15
- */
16
- createAction<Input, Success, Error>(program: (input: Input, effects: ApplicationBridgeEffects<Command, Receipt, HostEvent, Snapshot>) => Effect.Effect<Success, Error, ApplicationBridgeService>): SvelteEffectAction<Input, Success, Error>;
17
- dispose(): Promise<void>;
18
- }
19
- export declare function createEffectSvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot>(controller: ApplicationBridgeController<Command, Receipt, HostEvent, Snapshot>, options?: SvelteApplicationBridgeOptions<HostEvent, Snapshot>): EffectSvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot>;
@@ -1,46 +0,0 @@
1
- import { SvelteApplicationBridge } from "./bridge.svelte.js";
2
- import { SvelteEffectAction } from "./effect-action.svelte.js";
3
- /** Opt-in Effect surface backed by the Application Bridge's owned runtime. */
4
- export class EffectSvelteApplicationBridge extends SvelteApplicationBridge {
5
- effects;
6
- #effectController;
7
- #actions = [];
8
- constructor(controller, options = {}) {
9
- super(controller, options);
10
- this.#effectController = controller;
11
- this.effects = controller.effects;
12
- }
13
- run(program) {
14
- return this.#effectController.run(program);
15
- }
16
- runExit(program) {
17
- return this.#effectController.runExit(program);
18
- }
19
- /**
20
- * Creates a latest-wins action whose Fiber is interrupted when superseded or
21
- * when this application bridge is disposed.
22
- */
23
- createAction(program) {
24
- if (this.status === "disposed")
25
- throw new Error("The Svelte Application Bridge is disposed.");
26
- let action;
27
- action = new SvelteEffectAction(this.#effectController, (input) => program(input, this.effects), () => {
28
- const index = this.#actions.indexOf(action);
29
- if (index >= 0)
30
- this.#actions.splice(index, 1);
31
- });
32
- this.#actions.push(action);
33
- return action;
34
- }
35
- async dispose() {
36
- if (this.status === "disposed")
37
- return;
38
- const actions = [...this.#actions];
39
- this.#actions.length = 0;
40
- await Promise.all(actions.map((action) => action.dispose()));
41
- await super.dispose();
42
- }
43
- }
44
- export function createEffectSvelteApplicationBridge(controller, options = {}) {
45
- return new EffectSvelteApplicationBridge(controller, options);
46
- }
@@ -1,13 +0,0 @@
1
- export interface RunicHostedBrowserBootstrap {
2
- readonly schema: "runic.hosted-bootstrap/1";
3
- readonly fingerprint: string;
4
- }
5
- export interface RunicHostedBrowserBridge {
6
- start(): Promise<unknown>;
7
- dispose(): Promise<void>;
8
- }
9
- /**
10
- * Starts a browser bridge only after the SSR bootstrap marker has been checked.
11
- * The marker is a hydration-consistency guard, not an authorization credential.
12
- */
13
- export declare function startRunicHostedBridgeAfterBootstrap(bootstrap: RunicHostedBrowserBootstrap, bridge: RunicHostedBrowserBridge): boolean;
@@ -1,23 +0,0 @@
1
- /**
2
- * Starts a browser bridge only after the SSR bootstrap marker has been checked.
3
- * The marker is a hydration-consistency guard, not an authorization credential.
4
- */
5
- export function startRunicHostedBridgeAfterBootstrap(bootstrap, bridge) {
6
- if (bootstrap?.schema !== "runic.hosted-bootstrap/1" || !isFingerprint(bootstrap.fingerprint)) {
7
- throw new TypeError("The Runic hosted browser bootstrap is malformed.");
8
- }
9
- if (!bridge || typeof bridge.start !== "function" || typeof bridge.dispose !== "function") {
10
- throw new TypeError("The Runic hosted browser bridge is malformed.");
11
- }
12
- const marker = document.querySelector('meta[name="runic-hosted-bootstrap"]');
13
- if (!(marker instanceof HTMLMetaElement) || marker.content !== bootstrap.fingerprint) {
14
- document.documentElement.dataset.runicHostedHydration = "mismatch";
15
- return false;
16
- }
17
- delete document.documentElement.dataset.runicHostedHydration;
18
- void bridge.start().catch(() => undefined);
19
- return true;
20
- }
21
- function isFingerprint(value) {
22
- return typeof value === "string" && /^runic-hosted-[a-f0-9]{8}$/.test(value);
23
- }
package/dist/types.d.ts DELETED
@@ -1,35 +0,0 @@
1
- import type { ApplicationBridgeController, ApplicationBridgeEffects, ApplicationBridgeService, BridgeError } from "@runic-artifex/application-bridge";
2
- /** Public Application Bridge contracts, re-exported without a renderer-owned copy. */
3
- export type { ApplicationBridgeController, ApplicationBridgeEffects, ApplicationBridgeService, BridgeError, };
4
- export type ApplicationBridgeStatus = "idle" | "connecting" | "connected" | "reconnecting" | "error" | "disposed";
5
- export type EffectActionStatus = "idle" | "running" | "success" | "failure" | "interrupted" | "disposed";
6
- /**
7
- * Optional callbacks emitted by the Svelte projection. This deliberately stays
8
- * independent of any Vite implementation; use the `/vite` entry point to
9
- * connect it to Runic Toolkit DevTools.
10
- */
11
- export interface ApplicationBridgeObserver {
12
- state(state: Readonly<{
13
- connection?: Readonly<{
14
- state?: "connecting" | "connected" | "disconnected" | "closed";
15
- transport?: string;
16
- sessionId?: string;
17
- revision?: number;
18
- sequence?: number;
19
- }>;
20
- }>): void;
21
- trace(entry: Readonly<{
22
- kind: "command" | "receipt" | "event" | "operation" | "connection" | "error";
23
- label: string;
24
- detail?: Readonly<Record<string, unknown>>;
25
- }>): void;
26
- }
27
- export interface SvelteApplicationBridgeOptions<HostEvent, Snapshot> {
28
- readonly reduce?: (snapshot: Snapshot | undefined, event: HostEvent) => Snapshot | undefined;
29
- readonly observer?: ApplicationBridgeObserver;
30
- readonly inspectSnapshot?: (snapshot: Snapshot) => Readonly<{
31
- sessionId?: string;
32
- revision?: number;
33
- sequence?: number;
34
- }>;
35
- }
package/dist/vite.d.ts DELETED
@@ -1,7 +0,0 @@
1
- import type { ApplicationBridgeObserver } from "./types.js";
2
- /** Connects a Svelte bridge projection to the optional Runic Vite client. */
3
- export declare function createViteApplicationBridgeObserver(): ApplicationBridgeObserver;
4
- /** Preserves one application-owned resource across a Vite hot replacement. */
5
- export declare function preserveViteHmrResource<T>(key: string, create: () => T): T;
6
- /** Explicitly releases a resource preserved for Vite hot replacement. */
7
- export declare function disposeViteHmrResource(key: string, dispose?: (resource: unknown) => void | Promise<void>): Promise<void>;
package/dist/vite.js DELETED
@@ -1,39 +0,0 @@
1
- import { createRunicDiagnosticReporter, disposeRunicHmrResource, preserveRunicHmrResource, reportRunicState, } from "@runic-artifex/vite-plugin-runic/client";
2
- /** Connects a Svelte bridge projection to the optional Runic Vite client. */
3
- export function createViteApplicationBridgeObserver() {
4
- const reporter = createRunicDiagnosticReporter("application-bridge");
5
- return {
6
- state: (state) => reportRunicState(state),
7
- trace: (entry) => {
8
- const detail = boundedDetail(entry.detail);
9
- reporter.report({
10
- kind: entry.kind,
11
- label: entry.label,
12
- ...(detail === undefined ? {} : { detail }),
13
- });
14
- },
15
- };
16
- }
17
- function boundedDetail(detail) {
18
- if (detail === undefined)
19
- return undefined;
20
- const result = {};
21
- let count = 0;
22
- for (const [key, value] of Object.entries(detail)) {
23
- if (count === 12)
24
- break;
25
- if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null) {
26
- result[key] = value;
27
- count += 1;
28
- }
29
- }
30
- return count === 0 ? undefined : result;
31
- }
32
- /** Preserves one application-owned resource across a Vite hot replacement. */
33
- export function preserveViteHmrResource(key, create) {
34
- return preserveRunicHmrResource(key, create);
35
- }
36
- /** Explicitly releases a resource preserved for Vite hot replacement. */
37
- export function disposeViteHmrResource(key, dispose) {
38
- return disposeRunicHmrResource(key, dispose);
39
- }
File without changes