feat(sdk): expose app bar actions via props (#27)

* feat(sdk): extract theme source-of-truth module

* refactor(sdk): make useTheme subscribe to shared theme store

* feat(sdk): add useWorkflowBuilderActions hook (WB-217)

* feat(sdk): export useWorkflowBuilderActions from barrel (WB-217)

* docs: WB-217 no-app-bar layout guide + SDK README link + changeset

* feat(no-app-bar): reference app demonstrating useWorkflowBuilderActions (WB-217)

* feat(sdk): add LayoutChangeOptions to layout-direction actions (WB-217)

* chore: remove no-app-bar reference app (WB-217)

* fix(sdk): apply persisted theme to DOM on load (WB-217)

* refactor(sdk): tighten layout-direction actions API (WB-217)

* fix(sdk): apply theme on Root mount, not module load

- export the `Theme` type from the barrel; `WorkflowBuilderActions`
  already speaks in it
- validate the stored theme on read instead of casting, so `''` or an
  unrecognized value falls back to `light`
- correct the hook JSDoc and the no-app-bar guide: the app bar has no
  layout-direction control, so that action is additive, not a mirror
- tests: Root paints persisted theme on mount, read-validation fallback
- trim the three WB-217 changesets to release-note length and codify
  "keep changeset bodies short" in RELEASE.md

* docs: fold no-app-bar guide into React Component quick-start

* refactor(sdk): use getStoreNodes action in diagram effect

---------

Co-authored-by: Piotr Blaszczyk <piotr.blaszczyk@synergycodes.com>

Author: kacpercierzniewski

.changeset/wb-217-actions-hook.md

@@ -0,0 +1,5 @@
+---
+'@workflowbuilder/sdk': minor
+---
+
+feat: add `useWorkflowBuilderActions()`. Gives custom layouts that omit `<WorkflowBuilder.TopBar />` imperative save / import / export / settings / read-only / theme / layout-direction actions. Also exports the `WorkflowBuilderActions`, `LayoutChangeOptions`, and `Theme` types. See [Custom layout without the app bar](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/#custom-layout-without-the-app-bar).

.changeset/wb-217-flip-layout-stale-handles.md

@@ -0,0 +1,5 @@
+---
+'@workflowbuilder/sdk': patch
+---
+
+fix: re-measure node internals when `layoutDirection` changes, so edges re-route to the new handle positions instead of the stale ones React Flow had cached.

.changeset/wb-217-theme-shared-store.md

@@ -0,0 +1,5 @@
+---
+'@workflowbuilder/sdk': patch
+---
+
+fix: theme now lives in a shared store applied to the DOM on `<WorkflowBuilder.Root>` mount, so a persisted theme paints on first load even without the app bar and multiple consumers stay in sync. Reads of `document` / `localStorage` are guarded, so importing the SDK server-side no longer throws.

apps/docs/src/content/docs/get-started/quick-start/wb-as-react-component.mdx

@@ -147,6 +147,35 @@ To add custom overlays alongside the default layout, mount it explicitly:
 </WorkflowBuilder.Root>
 ```
 
+### Custom layout without the app bar
+
+`<WorkflowBuilder.TopBar />` ships the save, import / export, settings, read-only, and theme controls. When you omit it from a custom layout, reach the same commands through the `useWorkflowBuilderActions()` hook. Call it from any descendant of `<WorkflowBuilder.Root>` and wire the returned callbacks to your own buttons:
+
+```tsx
+import { useWorkflowBuilderActions } from '@workflowbuilder/sdk';
+
+function MyToolbar() {
+  const actions = useWorkflowBuilderActions();
+
+  return (
+    <header>
+      <button onClick={actions.save}>Save</button>
+      <button onClick={actions.openImport}>Import</button>
+      <button onClick={actions.openExport}>Export</button>
+      <button onClick={actions.openSettings}>Settings</button>
+      <button onClick={actions.toggleReadOnly}>Read-only</button>
+      <button onClick={actions.toggleDarkMode}>Theme</button>
+    </header>
+  );
+}
+```
+
+The hook returns a stable object, so you can pass any callback straight to an event handler. See [`WorkflowBuilderActions`](/api/hooks/workflowbuilderactions/) for the full action list. A few notes:
+
+- It must be called from a descendant of `<WorkflowBuilder.Root>`. `save` reads the active [integration strategy](#integration-strategies) via context, so calling the hook outside Root resolves `save()` to `'error'` and logs a warning.
+- The hook also exposes layout-direction control the bar does not surface: `setLayoutDirection('RIGHT' | 'DOWN')` (idempotent) and `toggleLayoutDirection({ flipPositions?, fitView? })`. `flipPositions` mirrors each node's `x`/`y` as a naive axis swap. It is not auto-layout and ignores node sizes, so pair it with `fitView`. That is why it lives only on the toggle, not on `setLayoutDirection`.
+- The top bar also shows and edits the document name. Render your own with `useStore`: read `s.documentName` and write through `s.setDocumentName`.
+
 ## Integration strategies
 
 | Strategy       | Source / sink                                               | When to use                  |

packages/sdk/README.md

@@ -85,6 +85,8 @@ To add custom overlays alongside the default layout, mount it explicitly:
 
 Each subcomponent is also exported under a named alias (`WorkflowBuilderTopBar`, `WorkflowBuilderPalette`, `WorkflowBuilderCanvas`, `WorkflowBuilderPropertiesPanel`, `WorkflowBuilderDefaultLayout`) for consumers who prefer the classic style.
 
+If you omit `<WorkflowBuilder.TopBar />`, use [`useWorkflowBuilderActions()`](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/#custom-layout-without-the-app-bar) to trigger save / import / export / settings / read-only / theme / layout-direction from your own controls.
+
 ## `<WorkflowBuilder.Root>` props
 
 | Prop               | Type                            | Description                                                                                                                                                                    |

packages/sdk/RELEASE.md

@@ -59,6 +59,8 @@ This part Claude (or any contributor) handles per change — not the maintainer.
 
    Skip the changeset only for changes that do not affect the published `dist/` (e.g. internal tests, lint config, comments).
 
+   **Keep the body short — it ships verbatim as a release note.** One sentence for a fix, one or two for a feature. State what changed and the consumer-facing effect, name the public symbols touched, and stop. No rationale, no implementation walk-through, no internal file names. Reasoning belongs in the PR description or code comments, not the release notes. Breaking changes are the only exception: add a `Breaking changes:` list with migration steps (see `remove-nodeid-from-handles.md`).
+
 4. Commit code + changeset together. Conventional Commits format is enforced by `.husky/commit-msg`:
 
    ```bash

packages/sdk/src/features/diagram/diagram.tsx

@@ -9,8 +9,9 @@ import {
   type OnSelectionChangeParams,
   ReactFlow,
   SelectionMode,
+  useUpdateNodeInternals,
 } from '@xyflow/react';
-import { type DragEventHandler, useCallback, useMemo } from 'react';
+import { type DragEventHandler, useCallback, useEffect, useMemo } from 'react';
 import type { DragEvent } from 'react';
 
 import styles from './diagram.module.css';
@@ -19,6 +20,7 @@ import '@xyflow/react/dist/style.css';
 import { usePaletteDrop } from '../../hooks/use-palette-drop';
 import type { WorkflowBuilderOnSelectionChangeParams } from '../../node/common';
 import type { WorkflowBuilderEdge, WorkflowBuilderNode } from '../../node/node-data';
+import { getStoreNodes } from '../../store/slices/diagram-slice/actions';
 import { useStore } from '../../store/store';
 import { trackFutureChange } from '../changes-tracker/stores/use-changes-tracker-store';
 import { useDeleteConfirmation } from '../modals/delete-confirmation/use-delete-confirmation';
@@ -70,6 +72,18 @@ function DiagramContainerComponent({ edgeTypes = {} }: DiagramContainerProps) {
   const setConnectionBeingDragged = useStore((store) => store.setConnectionBeingDragged);
   const nodeTypes = useNodeTypes();
 
+  // React Flow caches each handle's measured bounds in `nodeInternals`. When
+  // `layoutDirection` flips, existing nodes re-render their `<Handle>` with a
+  // new `position` prop, but the cache stays stale and edges keep routing to
+  // the old port spots. Ask React Flow to remeasure every mounted node when
+  // the direction changes.
+  const layoutDirection = useStore((store) => store.layoutDirection);
+  const updateNodeInternals = useUpdateNodeInternals();
+  useEffect(() => {
+    const ids = getStoreNodes().map((node) => node.id);
+    if (ids.length > 0) updateNodeInternals(ids);
+  }, [layoutDirection, updateNodeInternals]);
+
   const onDragOver = useCallback((event: DragEvent) => {
     event.preventDefault();
     event.dataTransfer.dropEffect = 'copy';

packages/sdk/src/hooks/theme.spec.ts

@@ -0,0 +1,80 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { getTheme, initTheme, setTheme, subscribeTheme } from './theme';
+
+describe('theme module', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    delete document.documentElement.dataset.theme;
+  });
+
+  afterEach(() => {
+    localStorage.clear();
+    delete document.documentElement.dataset.theme;
+  });
+
+  it('defaults to "light" when localStorage has no value', () => {
+    expect(getTheme()).toBe('light');
+  });
+
+  it('reads the persisted value from localStorage', () => {
+    localStorage.setItem('wb-theme', 'dark');
+    expect(getTheme()).toBe('dark');
+  });
+
+  it('falls back to "light" for an empty or unrecognized stored value', () => {
+    localStorage.setItem('wb-theme', '');
+    expect(getTheme()).toBe('light');
+
+    localStorage.setItem('wb-theme', 'Dark');
+    expect(getTheme()).toBe('light');
+  });
+
+  it('setTheme updates localStorage and the document attribute', () => {
+    setTheme('dark');
+
+    expect(localStorage.getItem('wb-theme')).toBe('dark');
+    expect(document.documentElement.dataset.theme).toBe('dark');
+    expect(getTheme()).toBe('dark');
+  });
+
+  it('setTheme notifies subscribers', () => {
+    const listener = vi.fn();
+    const unsubscribe = subscribeTheme(listener);
+
+    setTheme('dark');
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    unsubscribe();
+  });
+
+  it('setTheme does NOT notify subscribers when the value is unchanged', () => {
+    setTheme('light');
+    const listener = vi.fn();
+    const unsubscribe = subscribeTheme(listener);
+
+    setTheme('light');
+
+    expect(listener).not.toHaveBeenCalled();
+    unsubscribe();
+  });
+
+  it('initTheme applies the persisted theme to the DOM without a toggle', () => {
+    localStorage.setItem('wb-theme', 'dark');
+    delete document.documentElement.dataset.theme;
+
+    initTheme();
+
+    expect(document.documentElement.dataset.theme).toBe('dark');
+  });
+
+  it('unsubscribe removes the listener', () => {
+    const listener = vi.fn();
+    const unsubscribe = subscribeTheme(listener);
+    unsubscribe();
+
+    setTheme('dark');
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+});

packages/sdk/src/hooks/theme.ts

@@ -0,0 +1,47 @@
+const THEME_KEY = 'wb-theme';
+
+export type Theme = 'dark' | 'light';
+
+type Listener = () => void;
+
+const listeners = new Set<Listener>();
+
+function applyToDom(theme: Theme): void {
+  if (typeof document === 'undefined') return;
+  document.documentElement.dataset.theme = theme;
+}
+
+export function getTheme(): Theme {
+  if (typeof localStorage === 'undefined') return 'light';
+  const stored = localStorage.getItem(THEME_KEY);
+  return stored === 'dark' || stored === 'light' ? stored : 'light';
+}
+
+export function setTheme(theme: Theme): void {
+  const current = getTheme();
+  if (current === theme) return;
+
+  localStorage.setItem(THEME_KEY, theme);
+  applyToDom(theme);
+
+  for (const listener of listeners) listener();
+}
+
+export function subscribeTheme(listener: Listener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * Reflect the persisted theme on the DOM. Idempotent and SSR-safe (no-op when
+ * `document` is absent). Call once from the editor root's client-side mount
+ * effect so a saved non-default theme paints on first load without waiting for
+ * a `setTheme` toggle, including custom layouts that omit the app bar. Kept off
+ * the module's top level on purpose: a side effect at import would crash any
+ * server-side import of the SDK and could be dropped by tree-shaking.
+ */
+export function initTheme(): void {
+  applyToDom(getTheme());
+}

packages/sdk/src/hooks/use-theme.ts

@@ -1,21 +1,15 @@
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useSyncExternalStore } from 'react';
 
-const THEME_KEY = 'wb-theme';
-type Theme = 'dark' | 'light';
+import { getTheme, setTheme, subscribeTheme } from './theme';
 
 export function useTheme() {
-  const [theme, setTheme] = useState<Theme>(() => {
-    return (localStorage.getItem(THEME_KEY) || 'light') as Theme;
-  });
-
-  useEffect(() => {
-    document.documentElement.dataset.theme = theme;
-    localStorage.setItem(THEME_KEY, theme);
-  }, [theme]);
+  const theme = useSyncExternalStore(subscribeTheme, getTheme, getTheme);
 
   const toggleTheme = useCallback(() => {
-    setTheme((previous) => (previous === 'light' ? 'dark' : 'light'));
+    setTheme(getTheme() === 'light' ? 'dark' : 'light');
   }, []);
 
   return { theme, toggleTheme };
 }
+
+export { type Theme } from './theme';