@flowdrop/flowdrop 2.0.0-beta.3 → 2.0.0-beta.5

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0-beta.5] - 2026-06-20
+
+Fifth 2.0 beta, published under the npm `beta` dist-tag (`npm install @flowdrop/flowdrop@beta`). `latest` remains 1.15.0 until 2.0.0 GA. This release is a node-identity cleanup: node components now derive their instance id from the canonical `id` prop SvelteFlow already passes, dropping the duplicate `data.nodeId` copy and its load-time healing, and the node-_type_ entity id is renamed `metadata.id` → `metadata.node_type_id` to disambiguate it from the instance id. Six node components were also moved off the type-erasing `$props<T>()` onto a typed `interface Props`, which surfaced and fixed latent config-access errors in `ToolNode`.
+
+### Breaking Changes
+
+- **Node-type entity id renamed `metadata.id` → `metadata.node_type_id`.** The node-type entity id collided conceptually with the node _instance_ id; it is now `metadata.node_type_id` to disambiguate the two. It is a server-owned wire field, so the library preserves the snake_case name as a non-opinionated passthrough — adapters, the command type-map, connection validation, and the dynamic-schema paths were all updated to match. Consumers reading `metadata.id` for the node type must read `metadata.node_type_id`.
+- **Dropped the duplicate `data.nodeId` field.** Node components now derive their id from the canonical `id` prop that SvelteFlow already passes to every node, instead of a copy stored in `data.nodeId`. Handle ids, config-open callbacks, and status overlays read `id` directly. The field and its load-time "healing" are gone, so an intact graph can no longer look corrupted from a missing copy.
+
+### Changed (internal — no API change)
+
+- **Six node components typed properly.** The node components that used `$props<T>()` — which returns `any` and silently disabled type-checking — now declare an `interface Props` with `let props: Props = $props()`. This surfaced and fixed latent config-access errors in `ToolNode`.
+
+## [2.0.0-beta.4] - 2026-06-13
+
+Fourth 2.0 beta, published under the npm `beta` dist-tag (`npm install @flowdrop/flowdrop@beta`). `latest` remains 1.15.0 until 2.0.0 GA. This release is mostly an internal design-system consolidation pass — new shared `Button` / `IconButton` / `Input` / `Select` / `Textarea` primitives route every control through the `base.css` class system as the single source of truth, so themes (including Drafter) style fields and buttons consistently. User-visible changes are a navbar `end` snippet for embedding custom trailing controls, a new `--fd-control-radius` theming token, a range-slider fill fix, and opaque Drafter buttons. The archived Astro docs site is retired in favor of the Mintlify docs at `flowdrop.mintlify.app`.
+
+### Added
+
+- **`end` snippet on the navbar.** A new `end` snippet prop renders custom trailing content in the navbar (before the settings gear), letting consuming apps inject their own controls — e.g. a theme toggle — without forking the navbar.
+- **`--fd-control-radius` theming token.** Form controls (inputs, selects, textareas, the array action buttons, fieldset/checkbox-group/config-form borders) now read their corner radius from `--fd-control-radius`, so themes can tighten field corners independently of cards and panels. Drafter sets it to `2px` for its crisp blueprint look; other themes inherit the existing radius.
+
+### Fixed
+
+- **Range slider fill now tracks the thumb center.** The colored fill measured 0–100% of the raw track width while the browser keeps the thumb inside the track, so the fill and thumb drifted apart — worst at the extremes and visible on load. The fill now mirrors the thumb's actual travel (`thumb/2` to `100% − thumb/2`) via a new `--fd-range-fill` calc, with the thumb size tokenized.
+- **Drafter buttons are opaque and flat.** Several buttons in the Drafter skin (file-upload node config, canvas toggles) rendered with translucent backgrounds and read as see-through; they are now flat and opaque.
+
+### Changed (internal — no API change)
+
+- **Shared form-control and button primitives.** New typed `Button`, `IconButton`, `Input`, `Select`, and `Textarea` wrappers sit over the existing `.flowdrop-btn*` / `.flowdrop-input*` / `.flowdrop-btn--icon*` classes in `base.css`, making it the single source for control look (`:disabled` is the only muted state). `ThemeToggle`, the config form, sidebar search, the node swap picker, `FormArray` move/delete buttons, `InputCollector`, and the playground inputs were migrated onto them, dropping their hand-rolled, duplicated CSS. The primitives are internal (not exported), so their APIs aren't frozen before GA; public component prop APIs (e.g. `ThemeToggle`) are unchanged.
+- **`EditorStatusBar` extracted onto the shared button system.** The endpoint-error banner — previously inline in `App.svelte` with its own button CSS and a centered `80rem` layout — is now an `EditorStatusBar` component that routes actions through the `Button` primitive, spans the editor chrome flush, and uses a proper `CloseIcon` for dismissal. Added Storybook stories for `Button` and `EditorStatusBar`.
+- **Navbar control heights from one token.** Three hardcoded `height: 2.5rem` rules now use `var(--fd-size-btn-min)`, sharing a single source of truth with `.flowdrop-btn`.
+- **Extracted shared logic flagged by the duplication review.** `connections.ts` gains a shared `detectCycles()` (used by both `hasCycles` / `hasInvalidCycles`); `svelte-app.ts` extracts a `configureInstance()` shared by `mountFlowDropApp` / `mountWorkflowEditor`; and `FormField` / `FormFieldLight` share a `resolveBaseFieldType()` for the basic-type switch (with a unit test pinning resolution order) while keeping the deliberate full/light rendering split for the bundle-guard contract. No behavioral change.
+
+### Docs
+
+- **Retired the archived Astro/Starlight docs site (`apps/docs`)** and its docker-publish workflow; the Mintlify site at `flowdrop.mintlify.app` is canonical. All live documentation links (README, AGENTS, quick-start, i18n guide, API README, dev playground navbar, docker-playground landing, interrupt-feature doc) were repointed there. `apps/api-docs` is kept only to back the `api:lint` / `api:bundle` tooling and CI. Corrected the local dev-server port reference to the recommended Express demo.
+
 ## [2.0.0-beta.3] - 2026-06-12
 
 Third 2.0 beta, published under the npm `beta` dist-tag (`npm install @flowdrop/flowdrop@beta`). `latest` remains 1.15.0 until 2.0.0 GA. This release finishes the navbar/theme defaults pass started in beta.2 (navbar opt-in everywhere, light as the default theme, the FlowDrop wordmark in the header), adds the **Drafter** blueprint theme with per-theme canvas grids, and lands a keyboard-navigation and focus-ring overhaul alongside the 20px node-grid alignment.

package/README.md

@@ -23,10 +23,10 @@
 </p>
 
 <p align="center">
-  <a href="https://docs.flowdrop.io/getting-started/installation">Quickstart</a> •
+  <a href="https://flowdrop.mintlify.app/docs/quickstart">Quickstart</a> •
   <a href="#features">Features</a> •
   <a href="#integration">Integration</a> •
-  <a href="https://docs.flowdrop.io">Docs</a>
+  <a href="https://flowdrop.mintlify.app">Docs</a>
 </p>
 
 <p align="center">
@@ -139,7 +139,7 @@ Every user-facing string flows through a typed `Messages` tree. Pass a callback
 <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.
+Wire the callback to your i18n library (paraglide-js, sveltekit-i18n, etc.) — locale changes propagate automatically. See the [i18n & Custom Messages guide](https://flowdrop.mintlify.app/guides/i18n) for the full shape and a paraglide-js worked example.
 
 ## Sub-Module Exports
 
@@ -283,8 +283,8 @@ Runtime configuration means you build once and deploy to staging, production, or
 
 | Resource                                                                                     | Description              |
 | -------------------------------------------------------------------------------------------- | ------------------------ |
-| [QUICK_START.md](https://docs.flowdrop.io/getting-started/installation/)                     | Get running in 5 minutes |
-| [API Documentation](https://api.flowdrop.io/v1/)                                             | REST API specification   |
+| [QUICK_START.md](https://flowdrop.mintlify.app/docs/quickstart)                              | Get running in 5 minutes |
+| [API Documentation](https://flowdrop.mintlify.app/api-reference/introduction)                | REST API specification   |
 | [CHANGELOG.md](https://github.com/flowdrop-io/flowdrop/blob/main/libs/flowdrop/CHANGELOG.md) | Version history          |
 
 ## Development

package/dist/adapters/WorkflowAdapter.js

@@ -46,7 +46,7 @@ export class WorkflowAdapter {
      * Add a node to a workflow
      */
     addNode(workflow, nodeType, position, config) {
-        const metadata = this.nodeTypes.find((nt) => nt.id === nodeType);
+        const metadata = this.nodeTypes.find((nt) => nt.node_type_id === nodeType);
         if (!metadata) {
             throw new Error(`Node type '${nodeType}' not found`);
         }
@@ -248,7 +248,7 @@ export class WorkflowAdapter {
             description: svelteFlowWorkflow.description,
             nodes: svelteFlowWorkflow.nodes.map((node) => ({
                 id: node.id,
-                type: node.data.metadata.id,
+                type: node.data.metadata.node_type_id,
                 position: node.position,
                 data: {
                     label: node.data.label,
@@ -282,8 +282,7 @@ export class WorkflowAdapter {
                 data: {
                     label: node.data.label,
                     config: node.data.config,
-                    metadata: node.data.metadata,
-                    nodeId: node.id
+                    metadata: node.data.metadata
                 }
             })),
             edges: workflow.edges.map((edge) => ({
@@ -326,7 +325,7 @@ export class WorkflowAdapter {
         const nodeTypeCounts = new Map();
         cloned.nodes.forEach((node) => {
             const oldId = node.id;
-            const nodeTypeId = node.data.metadata.id;
+            const nodeTypeId = node.data.metadata.node_type_id;
             // Get the current count for this node type
             const currentCount = nodeTypeCounts.get(nodeTypeId) || 0;
             const newCount = currentCount + 1;

package/dist/adapters/agentspec/AgentSpecAdapter.js

@@ -266,7 +266,7 @@ export class AgentSpecAdapter {
             metadata: {
                 'flowdrop:position': node.position,
                 'flowdrop:node_id': node.id,
-                'flowdrop:node_type_id': node.data.metadata.id
+                'flowdrop:node_type_id': node.data.metadata.node_type_id
             }
         };
         // Add type-specific attributes from config
@@ -362,7 +362,7 @@ export class AgentSpecAdapter {
             return ext;
         }
         // Infer from FlowDrop node type ID
-        const fromId = extractComponentType(node.data.metadata.id);
+        const fromId = extractComponentType(node.data.metadata.node_type_id);
         if (fromId)
             return fromId;
         // Infer from FlowDrop visual type + category
@@ -404,7 +404,7 @@ export class AgentSpecAdapter {
         const nodeTypeId = asNode.metadata?.['flowdrop:node_type_id'] ||
             `${AGENTSPEC_NAMESPACE}.${asNode.component_type}`;
         const metadata = {
-            id: nodeTypeId,
+            node_type_id: nodeTypeId,
             name: defaults.defaultName,
             type: defaults.visualType,
             description: asNode.description || defaults.defaultDescription,

package/dist/adapters/agentspec/defaultNodeTypes.js

@@ -30,7 +30,7 @@ function buildRegistry() {
     registry.set('start_node', {
         componentType: 'start_node',
         metadata: {
-            id: `${AGENTSPEC_NS}.start_node`,
+            node_type_id: `${AGENTSPEC_NS}.start_node`,
             name: 'Start',
             type: 'terminal',
             description: 'Flow entry point. Defines the initial inputs for the flow.',
@@ -55,7 +55,7 @@ function buildRegistry() {
     registry.set('end_node', {
         componentType: 'end_node',
         metadata: {
-            id: `${AGENTSPEC_NS}.end_node`,
+            node_type_id: `${AGENTSPEC_NS}.end_node`,
             name: 'End',
             type: 'terminal',
             description: 'Flow exit point. Defines the final outputs of the flow.',
@@ -80,7 +80,7 @@ function buildRegistry() {
     registry.set('llm_node', {
         componentType: 'llm_node',
         metadata: {
-            id: `${AGENTSPEC_NS}.llm_node`,
+            node_type_id: `${AGENTSPEC_NS}.llm_node`,
             name: 'LLM',
             type: 'default',
             description: 'Generate text using a large language model with configurable prompts.',
@@ -145,7 +145,7 @@ function buildRegistry() {
     registry.set('branching_node', {
         componentType: 'branching_node',
         metadata: {
-            id: `${AGENTSPEC_NS}.branching_node`,
+            node_type_id: `${AGENTSPEC_NS}.branching_node`,
             name: 'Branch',
             type: 'gateway',
             description: 'Route execution to different paths based on conditions.',
@@ -213,7 +213,7 @@ function buildRegistry() {
     registry.set('tool_node', {
         componentType: 'tool_node',
         metadata: {
-            id: `${AGENTSPEC_NS}.tool_node`,
+            node_type_id: `${AGENTSPEC_NS}.tool_node`,
             name: 'Tool',
             type: 'tool',
             description: 'Execute a tool function with inputs and receive outputs.',
@@ -271,7 +271,7 @@ function buildRegistry() {
     registry.set('api_node', {
         componentType: 'api_node',
         metadata: {
-            id: `${AGENTSPEC_NS}.api_node`,
+            node_type_id: `${AGENTSPEC_NS}.api_node`,
             name: 'API Call',
             type: 'default',
             description: 'Make an HTTP API call with configurable endpoint, method, and headers.',
@@ -342,7 +342,7 @@ function buildRegistry() {
     registry.set('agent_node', {
         componentType: 'agent_node',
         metadata: {
-            id: `${AGENTSPEC_NS}.agent_node`,
+            node_type_id: `${AGENTSPEC_NS}.agent_node`,
             name: 'Agent',
             type: 'default',
             description: 'Run a multi-round agent conversation within the flow.',
@@ -400,7 +400,7 @@ function buildRegistry() {
     registry.set('flow_node', {
         componentType: 'flow_node',
         metadata: {
-            id: `${AGENTSPEC_NS}.flow_node`,
+            node_type_id: `${AGENTSPEC_NS}.flow_node`,
             name: 'Sub-Flow',
             type: 'simple',
             description: 'Execute another flow as a sub-routine within this flow.',
@@ -451,7 +451,7 @@ function buildRegistry() {
     registry.set('map_node', {
         componentType: 'map_node',
         metadata: {
-            id: `${AGENTSPEC_NS}.map_node`,
+            node_type_id: `${AGENTSPEC_NS}.map_node`,
             name: 'Map',
             type: 'default',
             description: 'Apply a flow or operation to each item in a collection (map-reduce).',

package/dist/commands/executor.js

@@ -76,7 +76,7 @@ function executeAddNode(command, context) {
         };
     }
     const position = command.position ?? computeAutoPosition(workflow.nodes);
-    const nodeId = generateNodeId(metadata.id, workflow.nodes);
+    const nodeId = generateNodeId(metadata.node_type_id, workflow.nodes);
     const config = extractConfigDefaults(metadata.configSchema);
     const node = {
         id: nodeId,
@@ -86,8 +86,7 @@ function executeAddNode(command, context) {
         data: {
             label: metadata.name,
             config,
-            metadata,
-            nodeId
+            metadata
         }
     };
     context.dispatch.addNode(node);
@@ -357,7 +356,7 @@ function executeInfo(command, context) {
     const resultData = {
         nodeId: shortId,
         label: node.data.label ?? metadata?.name ?? '',
-        type: metadata?.id ? toShortTypeId(metadata.id) : '',
+        type: metadata?.node_type_id ? toShortTypeId(metadata.node_type_id) : '',
         position: node.position,
         config: node.data.config ?? {},
         inputs,
@@ -578,7 +577,7 @@ function executeListNodes(context) {
     const nodes = workflow.nodes.map((n) => ({
         nodeId: toShortId(n.id),
         label: n.data.label ?? n.data.metadata?.name ?? '',
-        type: n.data.metadata?.id ? toShortTypeId(n.data.metadata.id) : ''
+        type: n.data.metadata?.node_type_id ? toShortTypeId(n.data.metadata.node_type_id) : ''
     }));
     const resultData = { nodes };
     return {
@@ -610,7 +609,7 @@ function executeListEdges(context) {
 }
 function executeListTypes(context) {
     const types = context.nodeTypes.map((m) => ({
-        typeId: toShortTypeId(m.id),
+        typeId: toShortTypeId(m.node_type_id),
         name: m.name,
         category: m.category
     }));

package/dist/commands/types.js

@@ -24,18 +24,18 @@ export function buildTypeMap(nodeTypes) {
     const shortIdCounts = new Map();
     // First pass: register full IDs and count short ID occurrences
     for (const metadata of nodeTypes) {
-        map.set(metadata.id, metadata);
-        const dotIndex = metadata.id.indexOf('.');
+        map.set(metadata.node_type_id, metadata);
+        const dotIndex = metadata.node_type_id.indexOf('.');
         if (dotIndex !== -1) {
-            const shortId = metadata.id.substring(dotIndex + 1);
+            const shortId = metadata.node_type_id.substring(dotIndex + 1);
             shortIdCounts.set(shortId, (shortIdCounts.get(shortId) ?? 0) + 1);
         }
     }
     // Second pass: register unique short IDs
     for (const metadata of nodeTypes) {
-        const dotIndex = metadata.id.indexOf('.');
+        const dotIndex = metadata.node_type_id.indexOf('.');
         if (dotIndex !== -1) {
-            const shortId = metadata.id.substring(dotIndex + 1);
+            const shortId = metadata.node_type_id.substring(dotIndex + 1);
             if (shortIdCounts.get(shortId) === 1) {
                 map.set(shortId, metadata);
             }

package/dist/components/App.svelte

@@ -10,6 +10,7 @@
   import WorkflowEditor from './WorkflowEditor.svelte';
   import NodeSidebar from './NodeSidebar.svelte';
   import CanvasIconButton from './CanvasIconButton.svelte';
+  import EditorStatusBar from './EditorStatusBar.svelte';
   import MenuIcon from './icons/MenuIcon.svelte';
   import MenuOpenIcon from './icons/MenuOpenIcon.svelte';
   import ConfigForm from './ConfigForm.svelte';
@@ -411,8 +412,8 @@
     if (propNodes && propNodes.length > 0) {
       // Merge format-provided nodes with prop nodes (deduplicate by ID, props take priority)
       const formatNodes = fd.formats.getAllFormatNodes();
-      const existingIds = new Set(propNodes.map((n) => n.id));
-      const uniqueFormatNodes = formatNodes.filter((n) => !existingIds.has(n.id));
+      const existingIds = new Set(propNodes.map((n) => n.node_type_id));
+      const uniqueFormatNodes = formatNodes.filter((n) => !existingIds.has(n.node_type_id));
       nodes = [...propNodes, ...uniqueFormatNodes];
       nodeTypesLoading = false;
       return;
@@ -428,8 +429,8 @@
 
       // Merge format-provided nodes with API nodes (deduplicate by ID, API takes priority)
       const formatNodes = fd.formats.getAllFormatNodes();
-      const existingIds = new Set(fetchedNodes.map((n) => n.id));
-      const uniqueFormatNodes = formatNodes.filter((n) => !existingIds.has(n.id));
+      const existingIds = new Set(fetchedNodes.map((n) => n.node_type_id));
+      const uniqueFormatNodes = formatNodes.filter((n) => !existingIds.has(n.node_type_id));
       nodes = [...fetchedNodes, ...uniqueFormatNodes];
       error = null;
       nodeTypesLoading = false;
@@ -1212,53 +1213,21 @@
     {/snippet}
 
     <!-- Main Content: Workflow Editor with Error Status -->
-    <!-- Status Display: aria-live announces API errors dynamically without requiring focus -->
     {#if error}
-      <div class="flowdrop-status flowdrop-status--error" aria-live="polite" aria-atomic="true">
-        <div class="flowdrop-status__content">
-          <div class="flowdrop-flex flowdrop-gap--3">
-            <div class="flowdrop-status__indicator flowdrop-status__indicator--error"></div>
-            <span class="flowdrop-text--sm flowdrop-font--medium">Error: {error}</span>
-          </div>
-          <div class="flowdrop-flex flowdrop-gap--2">
-            <button
-              class="flowdrop-btn flowdrop-btn--sm flowdrop-btn--primary"
-              onclick={retryLoad}
-              type="button"
-            >
-              Retry
-            </button>
-            <button
-              class="flowdrop-btn flowdrop-btn--sm flowdrop-btn--outline"
-              onclick={() => {
-                const defaultUrl = '/api/flowdrop';
-                const newUrl = prompt('Enter Backend API URL:', defaultUrl);
-                if (newUrl) {
-                  configureApi(createEndpointConfig(newUrl));
-                  fetchNodeTypes();
-                }
-              }}
-              type="button"
-            >
-              Set API URL
-            </button>
-            <button
-              class="flowdrop-btn flowdrop-btn--sm flowdrop-btn--outline"
-              onclick={testApiConnection}
-              type="button"
-            >
-              Test API
-            </button>
-            <button
-              class="flowdrop-btn flowdrop-btn--ghost flowdrop-btn--sm"
-              onclick={() => (error = null)}
-              type="button"
-            >
-              ✕
-            </button>
-          </div>
-        </div>
-      </div>
+      <EditorStatusBar
+        {error}
+        onRetry={retryLoad}
+        onSetApiUrl={() => {
+          const defaultUrl = '/api/flowdrop';
+          const newUrl = prompt('Enter Backend API URL:', defaultUrl);
+          if (newUrl) {
+            configureApi(createEndpointConfig(newUrl));
+            fetchNodeTypes();
+          }
+        }}
+        onTestApi={testApiConnection}
+        onDismiss={() => (error = null)}
+      />
     {/if}
 
     <!-- Main Editor Area -->
@@ -1314,106 +1283,6 @@
   .flowdrop-root {
     display: contents;
   }
-  /* Status bar styles */
-  .flowdrop-status {
-    background-color: var(--fd-info-muted);
-    border-bottom: 1px solid var(--fd-info);
-    padding: 1rem;
-  }
-
-  .flowdrop-status--error {
-    background-color: var(--fd-error-muted);
-    border-bottom: 1px solid var(--fd-error);
-  }
-
-  .flowdrop-status__content {
-    max-width: 80rem;
-    margin: 0 auto;
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-  }
-
-  .flowdrop-status__indicator {
-    width: 0.5rem;
-    height: 0.5rem;
-    border-radius: 50%;
-  }
-
-  .flowdrop-status__indicator--error {
-    background-color: var(--fd-error);
-  }
-
-  /* Button styles */
-  .flowdrop-btn {
-    padding: 0.375rem 0.75rem;
-    border-radius: var(--fd-radius-md);
-    font-size: 0.75rem;
-    font-weight: 500;
-    cursor: pointer;
-    border: 1px solid transparent;
-    transition: all var(--fd-transition-fast);
-  }
-
-  .flowdrop-btn--sm {
-    padding: 0.25rem 0.5rem;
-    font-size: 0.625rem;
-  }
-
-  .flowdrop-btn--outline {
-    background-color: transparent;
-    border-color: var(--fd-border);
-    color: var(--fd-foreground);
-  }
-
-  .flowdrop-btn--outline:hover {
-    background-color: var(--fd-muted);
-    border-color: var(--fd-border-strong);
-  }
-
-  .flowdrop-btn--primary {
-    background-color: var(--fd-primary);
-    border-color: var(--fd-primary);
-    color: var(--fd-primary-foreground);
-  }
-
-  .flowdrop-btn--primary:hover {
-    background-color: var(--fd-primary-hover);
-    border-color: var(--fd-primary-hover);
-  }
-
-  .flowdrop-btn--ghost {
-    background-color: transparent;
-    border-color: transparent;
-    color: var(--fd-muted-foreground);
-  }
-
-  .flowdrop-btn--ghost:hover {
-    background-color: var(--fd-muted);
-    color: var(--fd-foreground);
-  }
-
-  /* Utility classes */
-  .flowdrop-flex {
-    display: flex;
-  }
-
-  .flowdrop-gap--2 {
-    gap: 0.5rem;
-  }
-
-  .flowdrop-gap--3 {
-    gap: 0.75rem;
-  }
-
-  .flowdrop-text--sm {
-    font-size: 0.875rem;
-    line-height: 1.25rem;
-  }
-
-  .flowdrop-font--medium {
-    font-weight: 500;
-  }
 
   /* Floating sidebar toggle button — placement only; visuals live in CanvasIconButton */
   :global(.flowdrop-sidebar-fab) {

package/dist/components/Button.stories.svelte

@@ -0,0 +1,65 @@
+<script module lang="ts">
+  import type { ComponentProps } from 'svelte';
+  import { defineMeta } from '@storybook/addon-svelte-csf';
+  import Button from './Button.svelte';
+  import { fn } from 'storybook/test';
+
+  const { Story } = defineMeta({
+    title: 'Display/Button',
+    component: Button,
+    tags: ['autodocs'],
+    parameters: {
+      layout: 'centered'
+    },
+    argTypes: {
+      variant: {
+        control: { type: 'select' },
+        options: ['primary', 'secondary', 'outline', 'ghost']
+      },
+      size: {
+        control: { type: 'select' },
+        options: ['sm', 'md', 'lg']
+      },
+      disabled: { control: 'boolean' }
+    },
+    args: {
+      variant: 'secondary',
+      size: 'md',
+      disabled: false,
+      onclick: fn()
+    }
+  });
+</script>
+
+<!-- Arg-driven template so the Controls panel can tweak variant/size/disabled live. -->
+{#snippet template(args: Omit<ComponentProps<typeof Button>, 'children'>)}
+  <Button {...args}>Button</Button>
+{/snippet}
+
+<Story name="Primary" args={{ variant: 'primary' }} {template} />
+
+<Story name="Secondary" args={{ variant: 'secondary' }} {template} />
+
+<Story name="Outline" args={{ variant: 'outline' }} {template} />
+
+<Story name="Ghost" args={{ variant: 'ghost' }} {template} />
+
+<Story name="Disabled" args={{ variant: 'primary', disabled: true }} {template} />
+
+<!-- Static showcases comparing every variant / size side by side. -->
+<Story name="Variants" asChild>
+  <div style="display: flex; gap: 0.75rem; align-items: center;">
+    <Button variant="primary">Primary</Button>
+    <Button variant="secondary">Secondary</Button>
+    <Button variant="outline">Outline</Button>
+    <Button variant="ghost">Ghost</Button>
+  </div>
+</Story>
+
+<Story name="Sizes" asChild>
+  <div style="display: flex; gap: 0.75rem; align-items: center;">
+    <Button variant="primary" size="sm">Small</Button>
+    <Button variant="primary" size="md">Medium</Button>
+    <Button variant="primary" size="lg">Large</Button>
+  </div>
+</Story>

package/dist/components/Button.stories.svelte.d.ts

@@ -0,0 +1,19 @@
+import Button from './Button.svelte';
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const Button: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type Button = InstanceType<typeof Button>;
+export default Button;

package/dist/components/Button.svelte

@@ -0,0 +1,62 @@
+<!--
+  Button — typed wrapper over the shared `.flowdrop-btn` system (base.css).
+
+  All button styling (variants, sizes, the --fd-size-btn-min height token and the
+  centralized focus ring) lives in base.css. This component is the ergonomic,
+  type-safe entry point so callers pick `variant`/`size` instead of hand-writing
+  class strings — the single place new buttons should route through.
+
+  Internal for now (not exported from any public entry) so the API isn't frozen
+  before GA. Existing hand-rolled buttons migrate onto it incrementally.
+-->
+
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    /** Visual style — maps to `.flowdrop-btn--{variant}` in base.css */
+    variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
+    /** Size — `md` is the base `.flowdrop-btn`; `sm`/`lg` add a modifier */
+    size?: 'sm' | 'md' | 'lg';
+    /** Native button type */
+    type?: 'button' | 'submit' | 'reset';
+    /** Tooltip text */
+    title?: string;
+    /** Accessible label (use when the button is icon-only) */
+    ariaLabel?: string;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Extra classes appended to the root button */
+    class?: string;
+    /** Click handler */
+    onclick?: (event: MouseEvent) => void;
+    /** Button contents (icon, label, or both) */
+    children: Snippet;
+  }
+
+  let {
+    variant = 'secondary',
+    size = 'md',
+    type = 'button',
+    title,
+    ariaLabel,
+    disabled = false,
+    class: className = '',
+    onclick,
+    children
+  }: Props = $props();
+
+  // 'md' is the unmodified base class; only 'sm'/'lg' need a size modifier.
+  const sizeClass = $derived(size === 'md' ? '' : `flowdrop-btn--${size}`);
+</script>
+
+<button
+  class="flowdrop-btn flowdrop-btn--{variant} {sizeClass} {className}"
+  {type}
+  {title}
+  {disabled}
+  aria-label={ariaLabel}
+  {onclick}
+>
+  {@render children()}
+</button>