@flowdrop/flowdrop 1.15.0 → 2.0.0-beta.1

package/MIGRATION-2.0.md

@@ -0,0 +1,472 @@
+# Migrating to FlowDrop 2.0
+
+2.0's theme is **the explicit-instance era**: every compatibility shim the 1.x
+multi-instance refactor and the 1.8 message migration carried is gone. If your
+1.x code ran without deprecation warnings in the console, most of this guide
+does not apply to you.
+
+The sections are ordered by the shape of the change, from the deepest
+architectural moves (instances, the API client, registries) outward to module
+layout, data formats, component props, and storage. Each has a 1.x → 2.0 code
+example.
+
+## 1. Module-level store APIs are removed (the big one)
+
+All ~95 module-level functions that operated on "the" editor are gone:
+`getWorkflowStore()`, `workflowActions`, `historyService`, `getMessages()`,
+`playgroundActions`, `getCategories()`, `getHistoryState()`, and the rest of
+the get*/set*/actions surface from `@flowdrop/flowdrop/editor` and
+`@flowdrop/flowdrop/playground`.
+
+**Replacement:** every mount handle exposes its state container.
+
+```js
+// 1.x
+import { workflowActions, historyService, getMessages } from '@flowdrop/flowdrop/editor';
+const app = await mountFlowDropApp(el, options);
+workflowActions.addNode(node);
+historyService.undo();
+const messages = getMessages();
+
+// 2.0
+const app = await mountFlowDropApp(el, options);
+app.instance.workflow.actions.addNode(node);
+app.instance.history.undo();
+const messages = app.instance.playground.messages;
+```
+
+Inside Svelte components rendered under `<App>`/`<WorkflowEditor>`, resolve the
+owning instance with `getInstance()` (unchanged — including the browser
+fallback to the page-default instance for single-editor embeds):
+
+```svelte
+<script>
+  import { getInstance } from '@flowdrop/flowdrop/editor';
+  const fd = getInstance();
+  // fd.workflow, fd.history, fd.playground, fd.interrupts, fd.categories, …
+</script>
+```
+
+For hosts that construct state manually, the store classes are now exported:
+`WorkflowStore`, `HistoryStore`, `HistoryService`, `PlaygroundStore`,
+`InterruptStore`, `PortCoordinateStore`, plus `createFlowDropInstance()`.
+
+Settings remain page-global by design — `getSettings()` etc. are unchanged.
+
+## 2. API access is instance-scoped (`fd.api`)
+
+The module-level API singleton in `services/api.js` is gone:
+`setEndpointConfig()`, `getEndpointConfig()`, `nodeApi`, `workflowApi`, and the
+`api` aggregate are removed. Each instance now owns an `ApiContext` at
+`fd.api`, which holds the endpoint config + auth provider and lazily builds an
+`EnhancedFlowDropApiClient`.
+
+```js
+// 1.x
+import { setEndpointConfig, workflowApi, nodeApi } from '@flowdrop/flowdrop/editor';
+setEndpointConfig(createEndpointConfig('/api/flowdrop'));
+const nodes = await nodeApi.getNodes();
+const wf = await workflowApi.getWorkflow(id);
+
+// 2.0 — mount configures fd.api automatically; inside components resolve it:
+import { getInstance } from '@flowdrop/flowdrop/editor';
+const fd = getInstance();
+const nodes = await fd.api.client.getAvailableNodes();
+const wf = await fd.api.client.loadWorkflow(id);
+```
+
+`mountFlowDropApp` / `mountPlayground` / `<App>` call `fd.api.configure(config,
+authProvider)` for you. Services that previously read the singleton (playground,
+interrupt, chat, node-execution, dynamic-schema, variable) now take the endpoint
+config as their first argument — pass `fd.api.config`.
+
+### `EndpointConfig.auth` is removed — use an `AuthProvider`
+
+The `auth` block on `EndpointConfig` (and its header-injection branch) is gone.
+Authentication is supplied exclusively through an `AuthProvider`, passed to the
+mount/`<App>` `authProvider` option (or `fd.api.configure(config, provider)`).
+`StaticAuthProvider` covers the former static-token cases one-to-one:
+
+```js
+// 1.x
+createEndpointConfig('/api/flowdrop', {
+  auth: { type: 'bearer', token: TOKEN }
+});
+
+// 2.0
+import { StaticAuthProvider } from '@flowdrop/flowdrop';
+mountFlowDropApp(el, {
+  endpointConfig: createEndpointConfig('/api/flowdrop'),
+  authProvider: new StaticAuthProvider({ type: 'bearer', token: TOKEN })
+});
+```
+
+| 1.x `auth`                    | 2.0 `AuthProvider`                                    |
+| ----------------------------- | ----------------------------------------------------- |
+| `{ type: 'none' }`            | `new NoAuthProvider()` (or omit `authProvider`)       |
+| `{ type: 'bearer', token }`   | `new StaticAuthProvider({ type: 'bearer', token })`   |
+| `{ type: 'api_key', apiKey }` | `new StaticAuthProvider({ type: 'api_key', apiKey })` |
+| `{ type: 'custom', headers }` | `new StaticAuthProvider({ type: 'custom', headers })` |
+
+### Instance-scoped port compatibility
+
+`initializePortCompatibility()`, `getPortCompatibilityChecker()`, and
+`isPortCompatibilityInitialized()` are removed. Each instance owns a
+`PortCompatibilityChecker` at `fd.portCompatibility`, seeded with
+`DEFAULT_PORT_CONFIG` and re-initialized by mount from the backend's port
+config. The standalone connection helpers (`validateConnection`,
+`getPossibleConnections`, `getConnectionSuggestions`) now take the checker as
+their first argument.
+
+```js
+// 1.x
+import { initializePortCompatibility, validateConnection } from '@flowdrop/flowdrop/editor';
+initializePortCompatibility(portConfig);
+const ok = validateConnection(source, target);
+
+// 2.0
+import { getInstance } from '@flowdrop/flowdrop/editor';
+const fd = getInstance();
+const ok = validateConnection(fd.portCompatibility, source, target);
+```
+
+## 3. Registries are instance-scoped — importing the editor registers nothing
+
+In 1.x the node, field, and format registries were module singletons, and the
+editor barrel ran a side-effecting import that registered every builtin node the
+moment you imported it. In 2.0 each registry lives on the instance —
+`fd.nodes`, `fd.fields`, `fd.formats` — seeded in the constructor from read-only
+builtin definitions. There is no longer any import-time registration, and
+`package.json` `sideEffects` is now CSS-only (`["**/*.css"]`).
+
+The module-level registration functions and the singleton registry constants are
+removed:
+
+- `registerCustomNode()`, `createFlowDropPlugin()` / `registerFlowDropPlugin()`,
+  and `plugin.ts` are gone. Registration is now a registry method:
+  `fd.nodes.registerCustom(...)`, `fd.nodes.registerPlugin(...)`,
+  `fd.nodes.unregisterPlugin(...)`. `createPlugin().register(fd.nodes)` replaces
+  the module plugin functions.
+- The exported singleton consts `nodeComponentRegistry`, `fieldComponentRegistry`,
+  and `workflowFormatRegistry` are removed. Resolve the instance registry instead.
+
+```js
+// 1.x — module singletons + import-time side effects
+import { registerCustomNode, fieldComponentRegistry } from '@flowdrop/flowdrop/editor';
+registerCustomNode('myapp:color', 'Color Node', ColorNode);
+fieldComponentRegistry.register('color', {
+  component: MyColorField,
+  matcher: (schema) => schema.format === 'color'
+});
+
+// 2.0 — register against the instance after mount
+import { getInstance } from '@flowdrop/flowdrop/editor';
+const fd = getInstance();
+fd.nodes.registerCustom('myapp:color', 'Color Node', ColorNode);
+fd.fields.register('color', {
+  component: MyColorField,
+  matcher: (schema) => schema.format === 'color'
+});
+```
+
+Because registration is now post-mount by construction, late registrations have
+to invalidate `$derived` reads that already ran. `BaseRegistry` carries a
+`$state` version counter (the `editVersion` pattern) so dependent reads
+re-run when you register after the first paint — no host action required.
+
+The heavy form-field installers (`registerCodeEditorField`,
+`registerMarkdownEditorField`, and the template field) now take the **target
+registry explicitly** and re-check registration after their dynamic import
+resolves:
+
+```js
+// 1.x
+import { registerCodeEditorField } from '@flowdrop/flowdrop/form/code';
+registerCodeEditorField();
+
+// 2.0
+import { registerCodeEditorField } from '@flowdrop/flowdrop/form/code';
+import { getInstance } from '@flowdrop/flowdrop/editor';
+registerCodeEditorField(getInstance().fields);
+```
+
+Category color/icon helpers likewise take a `CategoriesStore` as an explicit
+parameter — the last global-instance fallback in `utils` is gone.
+
+`fd.fields.register()` warns in dev when it overwrites an existing field type.
+Overwriting still works (replacing a built-in field is legitimate); the warning
+flags accidental duplicates.
+
+## 4. Barrel de-duplication and the slim main entry
+
+### Each export keeps a single canonical home
+
+The editor barrel no longer re-exports playground internals, and the display
+barrel no longer re-exports `marked`.
+
+- **Playground exports** (`Playground`, `PlaygroundModal`, `ChatPanel`,
+  `SessionManager`, `InputCollector`, `ExecutionLogs`, `MessageBubble`,
+  `PlaygroundService`, `playgroundService`, `PlaygroundStore`) are removed from
+  `@flowdrop/flowdrop/editor`. Import them from `@flowdrop/flowdrop/playground`
+  instead.
+
+  ```js
+  // 1.x
+  import { Playground, playgroundService } from '@flowdrop/flowdrop/editor';
+
+  // 2.0
+  import { Playground, playgroundService } from '@flowdrop/flowdrop/playground';
+  ```
+
+- **`marked`** is no longer re-exported from `@flowdrop/flowdrop/display`. If you
+  need `marked` directly, install it as a dependency and import it from the
+  package:
+
+  ```js
+  // 1.x
+  import { marked } from '@flowdrop/flowdrop/display';
+
+  // 2.0 — `npm install marked`
+  import { marked } from 'marked';
+  ```
+
+### The main entry is now a minimal front door
+
+`@flowdrop/flowdrop` (the main entry) no longer re-exports the entire library.
+In 1.x it bundled every sub-module via `export *`; in 2.0 it exposes only the
+small surface most apps need to bootstrap:
+
+- **Values:** `App`, `mountFlowDropApp`, `unmountFlowDropApp`,
+  `createFlowDropInstance`, `getInstance`, `provideInstance`,
+  `createEndpointConfig`, `defaultEndpointConfig`, `NoAuthProvider`,
+  `StaticAuthProvider`, `CallbackAuthProvider`.
+- **Types:** `Workflow`, `WorkflowNode`, `WorkflowEdge`, `NodeMetadata`,
+  `ConfigSchema`, `EndpointConfig`, `AuthProvider`, `FlowDropInstance`,
+  `FlowDropMountOptions`, `MountedFlowDropApp`, `FlowDropEventHandlers`,
+  `Messages`, `MessagesOverride`.
+
+Everything else moves to a sub-module. If you imported a name from
+`@flowdrop/flowdrop` that is not in the list above, switch to the sub-module
+that owns it:
+
+| Name (1.x main entry)                                                                                                                        | 2.0 sub-module                         |
+| -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| `WorkflowEditor`, `ConfigForm`, `ConfigModal`, `ConfigPanel`, `Navbar`, `NodeSidebar`, node components                                       | `@flowdrop/flowdrop/editor`            |
+| `mountWorkflowEditor`, editor helper classes, `EnhancedFlowDropApiClient`, `ApiContext`                                                      | `@flowdrop/flowdrop/editor`            |
+| `WorkflowStore`, `HistoryStore`, `HistoryService`, `PortCoordinateStore`                                                                     | `@flowdrop/flowdrop/editor`            |
+| `globalSaveWorkflow`, `globalExportWorkflow`, `saveWorkflow`, `getWorkflow`, draft-storage helpers                                           | `@flowdrop/flowdrop/editor`            |
+| `fetchPortConfig`, `fetchCategories`, dynamic-schema helpers                                                                                 | `@flowdrop/flowdrop/editor`            |
+| `NodeExecutionService`, connection utilities, `PortCompatibilityChecker`                                                                     | `@flowdrop/flowdrop/editor`            |
+| Toast functions (`showSuccess`, `showError`, `showWarning`, `showInfo`, `showLoading`, `dismissToast`, `showPromise`, `showConfirmation`, …) | `@flowdrop/flowdrop/editor`            |
+| `SchemaForm`, `FormField`, `FormSelect`, `FormToggle`, `FormArray`, …, `AutocompleteConfig`                                                  | `@flowdrop/flowdrop/form`              |
+| `FormAutocomplete`                                                                                                                           | `@flowdrop/flowdrop/form/autocomplete` |
+| `registerCodeEditorField`                                                                                                                    | `@flowdrop/flowdrop/form/code`         |
+| `registerMarkdownEditorField`                                                                                                                | `@flowdrop/flowdrop/form/markdown`     |
+| `Playground`, `PlaygroundModal`, `ChatPanel`, `mountPlayground`, `PlaygroundService`                                                         | `@flowdrop/flowdrop/playground`        |
+| `MarkdownDisplay`                                                                                                                            | `@flowdrop/flowdrop/display`           |
+| `setMessages`, `mergeMessages`, `defaultMessages`                                                                                            | `@flowdrop/flowdrop/core`              |
+| Theme/skin exports (`defaultTheme`, `minimalTheme`, `resolveTheme`, `defaultSkin`, `slateSkin`)                                              | `@flowdrop/flowdrop/core`              |
+| Color-preference helpers (`theme`, `resolvedTheme`, `setTheme`, `toggleTheme`, …)                                                            | `@flowdrop/flowdrop/core`              |
+| `WorkflowAdapter`, `AgentSpecAdapter`, command DSL, color/icon utilities, all remaining types                                                | `@flowdrop/flowdrop/core`              |
+| Settings stores/services/components                                                                                                          | `@flowdrop/flowdrop/settings`          |
+
+```js
+// 1.x — everything from the main entry
+import { WorkflowEditor, SchemaForm, showSuccess, defaultTheme } from '@flowdrop/flowdrop';
+
+// 2.0 — import from the owning sub-module
+import { WorkflowEditor, showSuccess } from '@flowdrop/flowdrop/editor';
+import { SchemaForm } from '@flowdrop/flowdrop/form';
+import { defaultTheme } from '@flowdrop/flowdrop/core';
+```
+
+This also tightens tree-shaking: importing `App` and a couple of types from the
+main entry no longer pulls the form, display, playground, and settings barrels
+into your bundle.
+
+## 5. Workflow `metadata` is required and `version` → `schemaVersion`
+
+The workflow document's `metadata` object is now **required** on the `Workflow`
+type, and its `version` field has been renamed to `schemaVersion`. The rename
+disambiguates the document's _format_ version from any per-workflow revision
+number you may track yourself (and from `NodeMetadata.version`, the node-type
+version, which is **unchanged**).
+
+```ts
+// 1.x
+interface Workflow {
+  /* … */
+  metadata?: {
+    version: string; // ambiguous
+    createdAt: string;
+    updatedAt: string;
+    /* … */
+  };
+}
+
+// 2.0
+interface Workflow {
+  /* … */
+  metadata: {
+    schemaVersion: string; // the workflow schema format version
+    createdAt: string;
+    updatedAt: string;
+    /* … */
+  };
+}
+```
+
+### Load-time healing (automatic)
+
+You do **not** need to migrate stored workflow JSON by hand. Every workflow
+entry point — `WorkflowStore.initialize` (which backs `mountFlowDropApp`'s
+`workflow` option, drag-and-drop file import, and draft load) and
+`WorkflowAdapter.importWorkflow` — normalizes metadata on the way in:
+
+- **Missing `metadata`** → populated with required defaults (`schemaVersion`
+  from `WORKFLOW_SCHEMA_VERSION`, fresh `createdAt`/`updatedAt`).
+- **Legacy `metadata.version`** → copied into `schemaVersion` (when
+  `schemaVersion` is absent), then the legacy `version` key is dropped.
+
+Healing is idempotent: re-running it on an already-healed workflow is a no-op
+(round-trip stable). This mirrors the localStorage key migration in §8 — the
+runtime heals 1.x data on first read so existing documents keep loading.
+
+### What hosts reading workflow JSON need to know
+
+If your application reads or writes FlowDrop workflow JSON directly (outside the
+editor), update your code to read `metadata.schemaVersion` instead of
+`metadata.version`. Documents still on disk with the old `version` key continue
+to load through the editor unchanged, but newly serialized workflows will carry
+`schemaVersion`. The Agent Spec export still uses the namespaced
+`flowdrop:version` key (its source is now `metadata.schemaVersion`); that
+external key name is unchanged.
+
+The JSON Schema published at `@flowdrop/flowdrop/schema` reflects the rename —
+`WorkflowMetadata.required` is now `[schemaVersion, createdAt, updatedAt]`.
+
+## 6. Removed component props
+
+| Component                | Removed                                                                                          | Use instead                                                                                                                        |
+| ------------------------ | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `SchemaForm`             | `saveLabel`, `cancelLabel`                                                                       | `messages.form.schema.save` / `.cancel`                                                                                            |
+| `AIChatPanel`            | `placeholder`                                                                                    | `messages.chat.placeholder`                                                                                                        |
+| `ChatPanel`              | `showChatInput`, `showRunButton`                                                                 | `MessageStream` directly, or `ControlPanel` (keeps both flags)                                                                     |
+| `ChatPanel`              | `showLogs`                                                                                       | `fd.playground.setShowLogs(...)`                                                                                                   |
+| `WorkflowEditor`         | `nodes`, `height`, `width`, `isConfigSidebarOpen`, `selectedNodeForConfig`, `closeConfigSidebar` | These never did anything in 1.x. Size via `App`'s `height`/`width` (working since 1.16); node metadata flows through the instance. |
+| `App` / `WorkflowEditor` | `readOnly`, `lockWorkflow`                                                                       | A single `mode` prop — see [section 6.2](#62-mode-prop-replaces-readonly--lockworkflow).                                           |
+| `App`                    | `eventHandlers` (object)                                                                         | Flat `on*` props — see [section 6.3](#63-app-event-handlers-are-flat-props).                                                       |
+
+`FormToggle.onLabel`/`offLabel` and `FormArray.addLabel` were _un_-deprecated:
+they express per-instance labels the global messages system cannot, and are
+now documented overrides.
+
+Removed message keys (only the removed ChatPanel branches read them):
+`playground.states.viewOnlyTitle`, `.viewOnlyText`, `.readyTitle`, `.readyText`.
+
+### 6.1 `mountWorkflowEditor` option changes
+
+- `workflow` now actually loads the workflow (1.x accepted and ignored it).
+- `nodes` is removed (it fed a prop the editor never read). Use
+  `mountFlowDropApp` if you need to pre-seed node metadata.
+- `readOnly` / `lockWorkflow` mount options become a single `mode` option
+  (`'edit' | 'readonly' | 'locked'`) — see
+  [section 6.2](#62-mode-prop-replaces-readonly--lockworkflow). The grouped
+  `eventHandlers` mount option is **unchanged** (an options bag is fine in a JS
+  mount API); only the `<App>` _component_ prop is flattened.
+
+### 6.2 `mode` prop replaces `readOnly` + `lockWorkflow`
+
+`<App>`, `<WorkflowEditor>`, and the `mountFlowDropApp` options bag no longer
+take the `readOnly` and `lockWorkflow` booleans. They are replaced by a single
+`mode` prop/option:
+
+```ts
+mode?: 'edit' | 'readonly' | 'locked'; // default: 'edit'
+```
+
+**Behavior matrix** (what each mode gates):
+
+| mode         | node drag / connect / select | proximity-connect | node swap | bottom console panel + toggle |
+| ------------ | ---------------------------- | ----------------- | --------- | ----------------------------- |
+| `'edit'`     | enabled                      | enabled           | enabled   | available                     |
+| `'readonly'` | disabled                     | disabled          | disabled  | hidden                        |
+| `'locked'`   | disabled                     | disabled          | disabled  | hidden                        |
+
+In 1.x, `readOnly` and `lockWorkflow` gated the **exact same** interactions and
+were always combined as `!readOnly && !lockWorkflow`. Any combination of the two
+booleans therefore collapsed to either "edit" (both `false`) or "fully disabled"
+(either `true`) — there was no orthogonal behavior to lose. `'readonly'` and
+`'locked'` behave identically today; the two names are preserved as distinct
+intents so a future release can differentiate them without another breaking
+change.
+
+**Old → new mapping** (component prop and mount option are identical):
+
+| 1.x                                                        | 2.0                                                    |
+| ---------------------------------------------------------- | ------------------------------------------------------ |
+| `readOnly` unset / `false`, `lockWorkflow` unset / `false` | `mode="edit"` (or omit)                                |
+| `readOnly={true}`                                          | `mode="readonly"`                                      |
+| `lockWorkflow={true}`                                      | `mode="locked"`                                        |
+| both `true`                                                | `mode="readonly"` _or_ `mode="locked"` (same behavior) |
+
+```svelte
+<!-- 1.x -->
+<App readOnly={true} />
+<App lockWorkflow={true} />
+
+<!-- 2.0 -->
+<App mode="readonly" />
+<App mode="locked" />
+```
+
+```js
+// 1.x
+mountFlowDropApp(el, { readOnly: true });
+// 2.0
+mountFlowDropApp(el, { mode: 'readonly' });
+```
+
+### 6.3 `<App>` event handlers are flat props
+
+The `<App>` component no longer takes a grouped `eventHandlers={{ … }}` object.
+The handlers `<App>` consumes are now individual `on*` props, consistent with
+every other component:
+
+```svelte
+<!-- 1.x -->
+<App eventHandlers={{ onApiError, onAfterSave, onWorkflowLoad, onBeforeSwap }} />
+
+<!-- 2.0 -->
+<App {onApiError} {onAfterSave} {onWorkflowLoad} {onBeforeSwap} />
+```
+
+Available `<App>` callback props: `onBeforeSave`, `onAfterSave`, `onSaveError`,
+`onApiError`, `onWorkflowLoad`, `onBeforeSwap`, `onAfterSwap`.
+
+The **`mountFlowDropApp` / `mountPlayground` options bag is unchanged** — keep
+passing the grouped `eventHandlers` object there. The mount functions wire
+`onDirtyStateChange` / `onWorkflowChange` into the instance store, call
+`onBeforeUnmount` on teardown, and forward the remaining handlers to `<App>`'s
+flat props for you. The `FlowDropEventHandlers` type is still exported for use
+with the mount option.
+
+## 7. localStorage keys are instance-scoped
+
+The page-default instance no longer writes bare keys:
+
+| 1.x                           | 2.0                                   |
+| ----------------------------- | ------------------------------------- |
+| `flowdrop:draft:<workflowId>` | `flowdrop:draft:default:<workflowId>` |
+| `fd-pipeline-panel-open`      | `fd-pipeline-panel-open:default`      |
+
+Existing user data migrates automatically on first read (copy to the scoped
+key, remove the legacy key). Only hosts reading these keys directly need to
+update. `clearAllDrafts()` still removes everything under `flowdrop:draft:`.
+
+## 8. Behavioral notes
+
+- `fd.fields.register()` warns in dev when overwriting an existing field type.
+  Overwriting still works; the warning flags accidents.
+- Internal `DEV` gates use `esm-env` instead of `import.meta.env`, so the
+  package no longer assumes a Vite host.

package/README.md

@@ -50,7 +50,7 @@ No vendor lock-in. No data leaving your walls. No surprise bills.
 npm install @flowdrop/flowdrop
 ```
 
-> **Note:** FlowDrop supports **one editor instance per page** (module-level singleton stores). See [Architecture Notes](#architecture-notes) for details.
+> **Note:** FlowDrop supports **multiple editor instances per page** — each mount gets its own isolated state container. See [Architecture Notes](#architecture-notes) for details.
 
 You get a production-ready workflow UI. You keep full control of everything else.
 
@@ -58,11 +58,11 @@ You get a production-ready workflow UI. You keep full control of everything else
 
 ```svelte
 <script lang="ts">
-  import { WorkflowEditor } from '@flowdrop/flowdrop';
+  import { App } from '@flowdrop/flowdrop';
   import '@flowdrop/flowdrop/styles/base.css';
 </script>
 
-<WorkflowEditor />
+<App />
 ```
 
 **5 lines. One fully-functional workflow editor.**
@@ -80,7 +80,7 @@ You get a production-ready workflow UI. You keep full control of everything else
 
 ## Architecture Notes
 
-- **Single instance per page.** FlowDrop uses module-level singleton stores for state management. Only one FlowDrop editor instance can exist on a page at a time.
+- **Multiple instances per page.** Each mount gets its own `FlowDropInstance` state container (workflow, undo/redo history, playground sessions, registries, API context, drafts), so editors on the same page are fully isolated. In 2.0 there are no module-level store APIs — resolve state with `getInstance()` inside the component tree or the mount handle's `.instance` outside it. The first mount without an `instanceId` becomes the page-default instance; pass `instanceId` to additional mounts to scope their draft/panel storage keys. Theme and settings remain page-global by design.
 - **Svelte 5 required.** FlowDrop uses Svelte 5 runes (`$state`, `$derived`, `$effect`) throughout. Svelte 4 is not supported.
 - **Modern browsers only.** The library targets ES2020+ and does not include polyfills for older browsers.
 
@@ -112,12 +112,12 @@ FlowDrop includes a theme system with built-in light/dark support:
 
 ```svelte
 <script lang="ts">
-  import { WorkflowEditor } from '@flowdrop/flowdrop';
+  import { App } from '@flowdrop/flowdrop';
   import '@flowdrop/flowdrop/styles';
 </script>
 
 <!-- Built-in themes: 'default' or 'minimal' -->
-<WorkflowEditor theme="minimal" />
+<App theme="minimal" />
 ```
 
 Themes bundle a visual skin (CSS token palette) with behavioral UI defaults. You can also pass a custom theme object with your own skin tokens for full control over the light and dark palettes.
@@ -136,7 +136,7 @@ const app = await mountFlowDropApp(container, {
 Every user-facing string flows through a typed `Messages` tree. Pass a callback to override any subset:
 
 ```svelte
-<FlowDrop messages={() => ({ form: { schema: { save: 'Apply' } } })} />
+<App messages={() => ({ form: { schema: { save: 'Apply' } } })} />
 ```
 
 Wire the callback to your i18n library (paraglide-js, sveltekit-i18n, etc.) — locale changes propagate automatically. See the [i18n & Custom Messages guide](https://docs.flowdrop.io/guides/i18n) for the full shape and a paraglide-js worked example.
@@ -145,20 +145,20 @@ Wire the callback to your i18n library (paraglide-js, sveltekit-i18n, etc.) —
 
 FlowDrop provides tree-shakeable sub-module exports so you can import only what you need:
 
-| Export Path                        | Contents                                           |
-| ---------------------------------- | -------------------------------------------------- |
-| `@flowdrop/flowdrop`               | Full library (components, stores, services, types) |
-| `@flowdrop/flowdrop/core`          | Types and utilities only (no heavy dependencies)   |
-| `@flowdrop/flowdrop/editor`        | WorkflowEditor, stores, services                   |
-| `@flowdrop/flowdrop/form`          | SchemaForm, form fields, registry                  |
-| `@flowdrop/flowdrop/form/code`     | Code editor field (CodeMirror)                     |
-| `@flowdrop/flowdrop/form/markdown` | Markdown editor field                              |
-| `@flowdrop/flowdrop/display`       | MarkdownDisplay component                          |
-| `@flowdrop/flowdrop/playground`    | Playground components and services                 |
-| `@flowdrop/flowdrop/settings`      | SettingsPanel, stores, services                    |
-| `@flowdrop/flowdrop/styles`        | Base CSS stylesheet                                |
-| `@flowdrop/flowdrop/schema`        | Workflow JSON schema                               |
-| `@flowdrop/flowdrop/openapi`       | OpenAPI spec (YAML) for the FlowDrop backend API   |
+| Export Path                        | Contents                                                                                                               |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `@flowdrop/flowdrop`               | Slim front door: `App`, mount functions, `createFlowDropInstance`, `getInstance`, auth providers, core bootstrap types |
+| `@flowdrop/flowdrop/core`          | Types and utilities only (no heavy dependencies)                                                                       |
+| `@flowdrop/flowdrop/editor`        | WorkflowEditor, stores, services                                                                                       |
+| `@flowdrop/flowdrop/form`          | SchemaForm, form fields, registry                                                                                      |
+| `@flowdrop/flowdrop/form/code`     | Code editor field (CodeMirror)                                                                                         |
+| `@flowdrop/flowdrop/form/markdown` | Markdown editor field                                                                                                  |
+| `@flowdrop/flowdrop/display`       | MarkdownDisplay component                                                                                              |
+| `@flowdrop/flowdrop/playground`    | Playground components and services                                                                                     |
+| `@flowdrop/flowdrop/settings`      | SettingsPanel, stores, services                                                                                        |
+| `@flowdrop/flowdrop/styles`        | Base CSS stylesheet                                                                                                    |
+| `@flowdrop/flowdrop/schema`        | Workflow JSON schema                                                                                                   |
+| `@flowdrop/flowdrop/openapi`       | OpenAPI spec (YAML) for the FlowDrop backend API                                                                       |
 
 ### OpenAPI spec
 
@@ -170,12 +170,12 @@ The full OpenAPI spec for the FlowDrop backend API ships with the package, versi
 
 ```svelte
 <script>
-  import { WorkflowEditor, NodeSidebar } from '@flowdrop/flowdrop';
+  import { WorkflowEditor, NodeSidebar } from '@flowdrop/flowdrop/editor';
 </script>
 
 <div class="flex h-screen">
   <NodeSidebar {nodes} />
-  <WorkflowEditor {nodes} />
+  <WorkflowEditor />
 </div>
 ```
 

package/dist/adapters/WorkflowAdapter.d.ts

@@ -50,7 +50,7 @@ export interface StandardWorkflow {
     nodes: StandardNode[];
     edges: StandardEdge[];
     metadata?: {
-        version: string;
+        schemaVersion: string;
         createdAt: string;
         updatedAt: string;
         author?: string;

package/dist/adapters/WorkflowAdapter.js

@@ -13,6 +13,7 @@
  * - External applications that want to integrate with FlowDrop
  * - Systems that need to generate or modify workflows programmatically
  */
+import { WORKFLOW_SCHEMA_VERSION } from '../schemas/index.js';
 import { v4 as uuidv4 } from 'uuid';
 import { generateNodeId } from '../utils/nodeIds.js';
 /**
@@ -35,7 +36,7 @@ export class WorkflowAdapter {
             nodes: [],
             edges: [],
             metadata: {
-                version: '1.0.0',
+                schemaVersion: '1.0.0',
                 createdAt: new Date().toISOString(),
                 updatedAt: new Date().toISOString()
             }
@@ -222,13 +223,14 @@ export class WorkflowAdapter {
             if (!validation.valid) {
                 throw new Error(`Invalid workflow: ${validation.errors.join(', ')}`);
             }
-            // Update metadata
+            // Update metadata — heal legacy 1.x `version` key into `schemaVersion`.
+            const incoming = workflow.metadata;
             workflow.metadata = {
-                version: workflow.metadata?.version || '1.0.0',
-                createdAt: workflow.metadata?.createdAt || new Date().toISOString(),
+                schemaVersion: incoming?.schemaVersion || incoming?.version || '1.0.0',
+                createdAt: incoming?.createdAt || new Date().toISOString(),
                 updatedAt: new Date().toISOString(),
-                author: workflow.metadata?.author,
-                tags: workflow.metadata?.tags
+                author: incoming?.author,
+                tags: incoming?.tags
             };
             return workflow;
         }
@@ -291,7 +293,11 @@ export class WorkflowAdapter {
                 sourceHandle: edge.sourceHandle,
                 targetHandle: edge.targetHandle
             })),
-            metadata: workflow.metadata
+            metadata: workflow.metadata ?? {
+                schemaVersion: WORKFLOW_SCHEMA_VERSION,
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString()
+            }
         };
     }
     /**
@@ -337,7 +343,7 @@ export class WorkflowAdapter {
         cloned.id = uuidv4();
         cloned.name = newName || `${workflow.name} (Copy)`;
         cloned.metadata = {
-            version: cloned.metadata?.version || '1.0.0',
+            schemaVersion: cloned.metadata?.schemaVersion || '1.0.0',
             createdAt: new Date().toISOString(),
             updatedAt: new Date().toISOString(),
             author: cloned.metadata?.author,