@mindlogic-ai/logician-ui 4.0.0-alpha.9 → 5.0.0-alpha.0

package/src/components/Typography/Overline.tsx

@@ -1,5 +1,8 @@
 import { forwardRef } from 'react';
-import { Text, TextProps } from '@chakra-ui/react';
+import { Text } from '@chakra-ui/react';
+
+import { polymorphic } from '../../types/polymorphic';
+import { TypographyOwnProps } from './Typography.types';
 
 /**
  * Small, uppercase, letter-spaced label used as a section "eyebrow" or category
@@ -9,10 +12,10 @@ import { Text, TextProps } from '@chakra-ui/react';
  * Part of the typography scale alongside `Subtext` — it shares the subtext size
  * but adds the baked-in overline styling (`textStyle="overline"`: uppercase,
  * wider tracking, medium weight). Every aspect stays one Chakra prop away, so
- * brand/status variants are a single override (e.g. `color="primary.main"`,
+ * brand/status variants are a single override (e.g. `color="fg.default"`,
  * `fontWeight="extrabold"`).
  */
-export const Overline = forwardRef<HTMLParagraphElement, TextProps>(
+const OverlineImpl = forwardRef<HTMLParagraphElement, TypographyOwnProps>(
   (props, ref) => {
     const { fontSize, ...rest } = props;
 
@@ -22,7 +25,7 @@ export const Overline = forwardRef<HTMLParagraphElement, TextProps>(
         // If fontSize is provided, disable textStyle to allow the override
         textStyle={fontSize ? undefined : 'overline'}
         fontSize={fontSize}
-        color="slate.800"
+        color="fg.muted"
         wordBreak="keep-all"
         {...rest}
       />
@@ -30,4 +33,7 @@ export const Overline = forwardRef<HTMLParagraphElement, TextProps>(
   }
 );
 
-Overline.displayName = 'Overline';
+OverlineImpl.displayName = 'Overline';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const Overline = polymorphic<TypographyOwnProps, 'p'>(OverlineImpl);

package/src/components/Typography/Subtext.tsx

@@ -1,7 +1,10 @@
 import React, { forwardRef } from 'react';
-import { Text, TextProps } from '@chakra-ui/react';
+import { Text } from '@chakra-ui/react';
 
-export const Subtext = forwardRef<HTMLParagraphElement, TextProps>(
+import { polymorphic } from '../../types/polymorphic';
+import { TypographyOwnProps } from './Typography.types';
+
+const SubtextImpl = forwardRef<HTMLParagraphElement, TypographyOwnProps>(
   (props, ref) => {
     const { fontSize, ...rest } = props;
 
@@ -18,4 +21,7 @@ export const Subtext = forwardRef<HTMLParagraphElement, TextProps>(
   }
 );
 
-Subtext.displayName = 'Subtext';
+SubtextImpl.displayName = 'Subtext';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const Subtext = polymorphic<TypographyOwnProps, 'p'>(SubtextImpl);

package/src/components/Typography/Subtitle.tsx

@@ -1,14 +1,33 @@
 import { forwardRef } from 'react';
-import { Text, TextProps } from '@chakra-ui/react';
+import { Text } from '@chakra-ui/react';
 
-export const Subtitle = forwardRef<HTMLParagraphElement, TextProps>(
+import { polymorphic } from '../../types/polymorphic';
+import { TypographyOwnProps } from './Typography.types';
+
+/**
+ * Supporting text under a heading — a subtitle by role in the page, not by
+ * document structure.
+ *
+ * Renders a paragraph. It used to render `<h6>`, which made every call site a
+ * level-6 heading in the document outline: a sentence of helper copy under an
+ * `<h1>` announced as a heading to a screen reader, and a jump from level 1 to
+ * level 6 in the heading list (KWCAG 2.1 5.2.4.2 제목 제공 / axe `heading-order`).
+ * A component chosen for its type scale should not decide the outline.
+ *
+ * A subtitle that genuinely IS the next heading level still says so at the call
+ * site, which is where that is known:
+ *
+ * ```tsx
+ * <Subtitle as="h2">{sectionTitle}</Subtitle>
+ * ```
+ */
+const SubtitleImpl = forwardRef<HTMLParagraphElement, TypographyOwnProps>(
   (props, ref) => {
     const { fontSize, ...rest } = props;
 
     return (
       <Text
         ref={ref}
-        as="h6"
         textStyle={fontSize ? undefined : 'subtitle'}
         fontSize={fontSize}
         color="fg.muted"
@@ -19,4 +38,7 @@ export const Subtitle = forwardRef<HTMLParagraphElement, TextProps>(
   }
 );
 
-Subtitle.displayName = 'Subtitle';
+SubtitleImpl.displayName = 'Subtitle';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const Subtitle = polymorphic<TypographyOwnProps, 'p'>(SubtitleImpl);

package/src/components/Typography/Text.tsx

@@ -1,7 +1,10 @@
 import React, { forwardRef } from 'react';
-import { Text as ChakraText, TextProps } from '@chakra-ui/react';
+import { Text as ChakraText } from '@chakra-ui/react';
 
-export const Text = forwardRef<HTMLParagraphElement, TextProps>(
+import { polymorphic } from '../../types/polymorphic';
+import { TypographyOwnProps } from './Typography.types';
+
+const TextImpl = forwardRef<HTMLParagraphElement, TypographyOwnProps>(
   (props, ref) => {
     // Extract fontSize and textStyle to handle them conditionally
     const { fontSize, ...rest } = props;
@@ -21,4 +24,7 @@ export const Text = forwardRef<HTMLParagraphElement, TextProps>(
   }
 );
 
-Text.displayName = 'Text';
+TextImpl.displayName = 'Text';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const Text = polymorphic<TypographyOwnProps, 'p'>(TextImpl);

package/src/components/Typography/Typography.stories.tsx

@@ -1,6 +1,20 @@
 import { Meta, StoryObj } from '@storybook/react';
 
-import { H1, H2, H3, H4, H5, Link, Overline, Subtext, Subtitle, Text } from '.';
+import { InlineCode } from '../InlineCode';
+
+import {
+  Caption,
+  H1,
+  H2,
+  H3,
+  H4,
+  H5,
+  Link,
+  Overline,
+  Subtext,
+  Subtitle,
+  Text,
+} from '.';
 
 const meta = {
   title: 'Components/Typography',
@@ -48,6 +62,60 @@ export const AllTextStyles: Story = {
         Subtext - Lorem ipsum dolor sit amet,{' '}
         <Link href="https://example.com">consectetur adipiscing elit</Link>
       </Subtext>
+      <Caption {...props}>
+        Caption - Lorem ipsum dolor sit amet,{' '}
+        <Link href="https://example.com">consectetur adipiscing elit</Link>
+      </Caption>
+    </>
+  ),
+};
+
+// InlineCode nested in each type tier. InlineCode's size is em-relative
+// (textStyle="subtext"), so it tracks whatever it sits in: a readable step below
+// body in a paragraph, and proportionally smaller inside a heading. Use this to
+// eyeball the step-down per context and to confirm a caller's `fontFamily="mono"`
+// still wins (InlineCode has no mono default). Pair with `AllTextStyles` above.
+export const InlineCodeInTextStyles: Story = {
+  render: () => {
+    const code = <InlineCode fontFamily="mono">inline_code()</InlineCode>;
+    return (
+      <>
+        <H1>H1 heading with {code} inside</H1>
+        <H2>H2 heading with {code} inside</H2>
+        <H3>H3 heading with {code} inside</H3>
+        <H4>H4 heading with {code} inside</H4>
+        <H5>H5 heading with {code} inside</H5>
+        <Text>Paragraph body text with {code} mid-sentence.</Text>
+        <Subtitle>Subtitle with {code} inside</Subtitle>
+        <Subtext>Subtext with {code} inside</Subtext>
+        <Caption>Caption with {code} inside</Caption>
+      </>
+    );
+  },
+};
+
+/**
+ * `as` swaps the rendered element **and** the props it accepts.
+ *
+ * This scale is a *type* scale, not a document outline. The two are chosen for
+ * different reasons — size by layout, heading level by structure — so `as` is
+ * how a call site keeps one while fixing the other. KWCAG 제목 제공 grades the
+ * level, and a screen reader's heading list is built from it; neither can see
+ * how large the text looks.
+ *
+ * `htmlFor` on the last line is a `<label>` prop, and it type-checks because
+ * `as="label"` carried it in. Before, `as="label"` rendered a label that no
+ * form control could be pointed at.
+ */
+export const AsElement: Story = {
+  render: () => (
+    <>
+      <H3 as="h2">h3 크기, 문서 구조상 h2</H3>
+      <Subtitle as="h2">제목이 맞을 때만 제목으로</Subtitle>
+      <Subtitle>보통은 문단으로 남는다</Subtitle>
+      <Text as="label" htmlFor="email">
+        이메일
+      </Text>
     </>
   ),
 };

package/src/components/Typography/Typography.types.ts

@@ -1,3 +1,48 @@
-import { TextProps } from '@chakra-ui/react';
+import type { ElementType } from 'react';
+import {
+  HeadingProps as ChakraHeadingProps,
+  TextProps,
+} from '@chakra-ui/react';
 
-export type TypographyProps = TextProps;
+// Relative, NOT `@/types/*`. Path aliases survive into the emitted `.d.ts` and
+// resolve against the CONSUMER's tsconfig, which silently degrades the type to
+// `any`. See `src/types/polymorphic.ts`.
+import type { PolymorphicProps } from '../../types/polymorphic';
+
+export type TypographyOwnProps = Omit<TextProps, 'as'>;
+
+/**
+ * Props for the body-text scale (`Text`, `Subtitle`, `Subtext`, `Caption`,
+ * `Overline`), typed for whatever element `as` renders. Defaults to `'p'`, so
+ * the bare type means exactly what it meant before.
+ *
+ * The scale is a *type* scale, not a document outline — which is why `as` is
+ * the documented escape hatch on these. A subtitle that genuinely is the next
+ * heading says so at the call site, where that is known:
+ *
+ * ```tsx
+ * <Subtitle as="h2">{sectionTitle}</Subtitle>
+ * <Text as="label" htmlFor="email">이메일</Text>
+ * ```
+ *
+ * The second line is the reason this needs to be polymorphic and not merely
+ * permitted: `as="label"` already compiled, but `htmlFor` did not come with it.
+ */
+export type TypographyProps<TElement extends ElementType = 'p'> =
+  PolymorphicProps<TElement, TypographyOwnProps>;
+
+export type HeadingOwnProps = Omit<ChakraHeadingProps, 'as'>;
+
+/**
+ * Props for `H1`–`H5`, typed for whatever element `as` renders.
+ *
+ * Each defaults to its own tag, so the bare type is unchanged. `as` is how a
+ * call site keeps the type scale while fixing the document outline — KWCAG
+ * 제목 제공 grades the heading LEVEL, not the size:
+ *
+ * ```tsx
+ * <H3 as="h2">{sectionTitle}</H3>
+ * ```
+ */
+export type HeadingProps<TElement extends ElementType = 'h1'> =
+  PolymorphicProps<TElement, HeadingOwnProps>;

package/src/components/Typography/index.ts

@@ -1,10 +1,11 @@
 // Component exports
+export { Caption } from './Caption';
 export { H1 } from './H1';
 export { H2 } from './H2';
 export { H3 } from './H3';
 export { H4 } from './H4';
 export { H5 } from './H5';
-export { Link } from './Link';
+export { Link, LINK_RAMP } from './Link';
 export { Overline } from './Overline';
 export { Subtext } from './Subtext';
 export { Subtitle } from './Subtitle';
@@ -13,16 +14,22 @@ export { Text } from './Text';
 // Type exports
 export type { LinkCustomProps as LinkProps } from './Link';
 export type {
+  TypographyProps as CaptionProps,
   TypographyProps as OverlineProps,
   TypographyProps as SubtextProps,
   TypographyProps as SubtitleProps,
   TypographyProps as TextProps,
+  TypographyOwnProps,
   TypographyProps,
 } from './Typography.types';
+// The heading props now come from our own polymorphic type rather than
+// Chakra's, so `as` carries the element's props with it.
 export type {
   HeadingProps as H1Props,
   HeadingProps as H2Props,
   HeadingProps as H3Props,
   HeadingProps as H4Props,
   HeadingProps as H5Props,
-} from '@chakra-ui/react';
+  HeadingOwnProps,
+  HeadingProps,
+} from './Typography.types';

package/src/components/Workflow/README.md

@@ -8,7 +8,7 @@ domain by registering node types, and you wire up the surrounding chrome
 (persistence, validation, an inspector) however your app wants.
 
 > Mental model: this is to a workflow editor what React Flow is to a canvas —
-> batteries for the editor, but *you bring the nodes* (and decide what clicking
+> batteries for the editor, but _you bring the nodes_ (and decide what clicking
 > one does).
 
 - [Quick start](#quick-start)
@@ -52,7 +52,7 @@ const messageNode = defineNodeType<MessageConfig>({
   icon: Sparkles,
   defaultConfig: () => ({ text: '' }),
   handles: () => ({ inputs: [{ id: 'in' }], outputs: [{ id: 'out' }] }),
-  getMetaChips: config => (config.text ? [config.text] : []),
+  getMetaChips: (config) => (config.text ? [config.text] : []),
   // Optional: the body shown in the inspector drawer when this node is selected.
   renderDrawer: ({ config, onChange, readOnly }) => (
     <FormControl>
@@ -60,7 +60,7 @@ const messageNode = defineNodeType<MessageConfig>({
       <Input
         value={config.text}
         disabled={readOnly}
-        onChange={e => onChange({ ...config, text: e.target.value })}
+        onChange={(e) => onChange({ ...config, text: e.target.value })}
       />
     </FormControl>
   ),
@@ -92,24 +92,24 @@ A node type is a plain object created with `defineNodeType<TConfig>(...)`, where
 `TConfig` is the shape of that node's `config`. The framework knows nothing about
 your kinds — it just renders what the registry describes.
 
-| Field | Required | Purpose |
-| --- | --- | --- |
-| `kind` | ✓ | Stable id for the type (e.g. `'message'`). Used in `node.kind` and id generation. Keep it English/snake-ish. |
-| `label` | ✓ | Short operational noun shown on the card and in the palette. Intentionally **not** translated (matches n8n/Make/Dify). |
-| `category` | ✓ | One of `trigger` · `ai` · `logic` · `safety` · `output` · `note`. Drives the icon-tile color. Color attaches to **category**, not kind. |
-| `icon` | ✓ | A `CreatedIcon` (wrap any icon with `createIcon` from this package, or use one of the exported icons). |
-| `defaultConfig` | ✓ | Value or factory `() => TConfig` for a freshly-dropped node. Prefer the factory for nested/mutable defaults. |
-| `handles` | ✓ | `(config) => ({ inputs, outputs })`. Can depend on config (e.g. a classifier emitting one output per category). |
-| `renderDrawer` | – | The inspector body for this kind. Omit and clicking the node is a no-op for editing. |
-| `renderNode` | – | Escape hatch to fully replace the card body (e.g. a sticky Note). Most types use `getInstanceTitle` + `getMetaChips` instead. |
-| `getInstanceTitle` | – | `(config) => string` for the snake_case identifier line. Defaults to the node id. |
-| `getMetaChips` | – | `(config) => (string \| { text, tone })[]` — small chips under the title. `tone: 'danger' \| 'warning'` tints a value. |
-| `descriptionKey` / `description` | – | Palette description. Prefer `descriptionKey` (resolved through your `translate`). |
-| `placement` | – | Declarative constraints read by the palette/canvas: `minCount`, `maxCount`, `pinned` (can't delete), `role: 'start' \| 'end'`, `mustFollow(Directly)`. |
-| `canConnect` | – | `(ctx) => boolean \| string` to reject a connection (return a reason string to explain). |
-| `outputSchema` | – | `(config) => JSONSchema \| undefined` for variable-resolution features. |
-| `getGraphIssues` | – | FE, graph-aware advisories merged into the node's canvas chrome (e.g. an unconnected required exit). Pure + cheap; runs every render. |
-| `localizeDefaults` / `hostDefaults` | – | Overlay defaults at creation time using the translator / the `hostBridge` (e.g. seed a node's model from the tenant's live list). |
+| Field                               | Required | Purpose                                                                                                                                                |
+| ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `kind`                              | ✓        | Stable id for the type (e.g. `'message'`). Used in `node.kind` and id generation. Keep it English/snake-ish.                                           |
+| `label`                             | ✓        | Short operational noun shown on the card and in the palette. Intentionally **not** translated (matches n8n/Make/Dify).                                 |
+| `category`                          | ✓        | One of `trigger` · `ai` · `logic` · `safety` · `output` · `note`. Drives the icon-tile color. Color attaches to **category**, not kind.                |
+| `icon`                              | ✓        | A `CreatedIcon` (wrap any icon with `createIcon` from this package, or use one of the exported icons).                                                 |
+| `defaultConfig`                     | ✓        | Value or factory `() => TConfig` for a freshly-dropped node. Prefer the factory for nested/mutable defaults.                                           |
+| `handles`                           | ✓        | `(config) => ({ inputs, outputs })`. Can depend on config (e.g. a classifier emitting one output per category).                                        |
+| `renderDrawer`                      | –        | The inspector body for this kind. Omit and clicking the node is a no-op for editing.                                                                   |
+| `renderNode`                        | –        | Escape hatch to fully replace the card body (e.g. a sticky Note). Most types use `getInstanceTitle` + `getMetaChips` instead.                          |
+| `getInstanceTitle`                  | –        | `(config) => string` for the snake_case identifier line. Defaults to the node id.                                                                      |
+| `getMetaChips`                      | –        | `(config) => (string \| { text, tone })[]` — small chips under the title. `tone: 'danger' \| 'warning'` tints a value.                                 |
+| `descriptionKey` / `description`    | –        | Palette description. Prefer `descriptionKey` (resolved through your `translate`).                                                                      |
+| `placement`                         | –        | Declarative constraints read by the palette/canvas: `minCount`, `maxCount`, `pinned` (can't delete), `role: 'start' \| 'end'`, `mustFollow(Directly)`. |
+| `canConnect`                        | –        | `(ctx) => boolean \| string` to reject a connection (return a reason string to explain).                                                               |
+| `outputSchema`                      | –        | `(config) => JSONSchema \| undefined` for variable-resolution features.                                                                                |
+| `getGraphIssues`                    | –        | FE, graph-aware advisories merged into the node's canvas chrome (e.g. an unconnected required exit). Pure + cheap; runs every render.                  |
+| `localizeDefaults` / `hostDefaults` | –        | Overlay defaults at creation time using the translator / the `hostBridge` (e.g. seed a node's model from the tenant's live list).                      |
 
 `resolveDefaultConfig(def)` is exported if you need to materialize a default
 config yourself.
@@ -138,7 +138,7 @@ each node type's `renderDrawer` — that's where domain-specific UI lives (model
 pickers, validators, even modals). The framework never sees it.
 
 **3. Fully custom — drive your own UI.** Omit `<NodeInspector>` entirely and render
-your own panel *anywhere in your app* from the selection signal. See below.
+your own panel _anywhere in your app_ from the selection signal. See below.
 
 ---
 
@@ -182,10 +182,73 @@ to keep the built-in drawer but also highlight the selection elsewhere.
 
 ---
 
+## Adding nodes from your own UI (`useWorkflowActions`)
+
+The palette is drag-and-drop. For anything else — a tap-to-add sheet on touch
+devices, a "+" beside a node, a command menu — call `useWorkflowActions()` from a
+component rendered inside `<Workflow>` (its `children` or
+`renderSelectedNodeToolbar`). It uses the same node builder as a palette drop
+(`{kind}_{N}` id; `defaultConfig` → `localizeDefaults` → `hostDefaults`), so you
+never rebuild ids, configs or placement, and you never import `@xyflow/react`.
+
+```tsx
+import {
+  useWorkflow,
+  useWorkflowActions,
+  Workflow,
+} from '@mindlogic-ai/logician-ui';
+
+function AddAgentButton() {
+  const { editor } = useWorkflow();
+  const { addNode, getAddAfterSource } = useWorkflowActions();
+  const after = getAddAfterSource(editor.selectedNodeId);
+  return (
+    <button
+      onClick={() =>
+        addNode(
+          'agent',
+          after ? { after: after.nodeId } : { at: 'viewportCenter' }
+        )
+      }
+    >
+      {after ? `Add after ${after.label}` : 'Add at centre'}
+    </button>
+  );
+}
+
+<Workflow
+  nodeTypes={NODE_TYPES}
+  renderSelectedNodeToolbar={(node) => <PlusAfter nodeId={node.id} />}
+>
+  <AddAgentButton />
+</Workflow>;
+```
+
+- `addNode(kind, target, { inspector? })` → `{ nodeId, edgeId | null } | null`.
+  - `{ after: nodeId }` places the node to that node's right and wires it from the
+    first free exit. No edge when the new kind has no entry (Note) or a
+    `canConnect` hook / connection rule rejects it. A node with no free exit (End,
+    Note, every exit taken) falls back to the viewport centre.
+  - `{ at: 'viewportCenter' }` places it unconnected in the middle of the view.
+  - Either way the node moves down past anything already there, becomes the
+    selection, and the view pans to it. Node + edge are **one undo step**.
+  - `inspector`: `'follow'` (default — an open inspector moves to the new node),
+    `'open'`, or `'close'`.
+  - Returns `null` without changing anything when read-only, the kind is not
+    registered, or its id is taken (a second `start`).
+- `getAddAfterSource(nodeId)` → `{ nodeId, sourceHandle, label } | null` — the
+  exit an add-after would use; `null` means the add would land at the centre.
+  `canAddAfter(nodeId)` is the boolean form.
+- `renderSelectedNodeToolbar(node)` (a `<Workflow>` prop) renders your content
+  beside the selected node's exit side, in screen space (constant size at any
+  zoom). Return `null` to show nothing.
+
+---
+
 ## Controlled vs uncontrolled graph
 
 - **Controlled:** pass `graph` and `onGraphChange`. You own the source of truth.
-  Pass a *stable* reference and update it from `onGraphChange`.
+  Pass a _stable_ reference and update it from `onGraphChange`.
 - **Uncontrolled:** pass `defaultGraph` (or nothing) and read changes via
   `onGraphChange` if you like. The component keeps its own state.
 
@@ -220,7 +283,7 @@ reload.
 
 ## Validation & issues
 
-Validation is **not** built in — the editor *renders* issues you supply, it does
+Validation is **not** built in — the editor _renders_ issues you supply, it does
 not compute them. This keeps the source of truth wherever it belongs (usually
 your backend).
 
@@ -228,7 +291,7 @@ your backend).
 <Workflow
   nodeTypes={NODE_TYPES}
   graph={graph}
-  issues={issues}            // Issue[] you own — render-only
+  issues={issues} // Issue[] you own — render-only
   validating={isRevalidating} // show a "rechecking" affordance, keep prior issues
 />
 ```
@@ -237,10 +300,10 @@ your backend).
 type Issue = {
   severity: 'error' | 'warning';
   code: string;
-  message: string;              // English fallback
-  nodeId?: string;             // attaches to a node
-  edgeId?: string;             // attaches to an edge
-  fieldKey?: string;           // renders inline under a specific field
+  message: string; // English fallback
+  nodeId?: string; // attaches to a node
+  edgeId?: string; // attaches to an edge
+  fieldKey?: string; // renders inline under a specific field
   messageVars?: Record<string, string | number>;
 };
 ```
@@ -308,7 +371,13 @@ depends on it.
 
 ```tsx
 // Static, read-only thumbnail.
-<Workflow nodeTypes={NODE_TYPES} graph={graph} readOnly showPalette={false} minHeight={0} />
+<Workflow
+  nodeTypes={NODE_TYPES}
+  graph={graph}
+  readOnly
+  showPalette={false}
+  minHeight={0}
+/>
 ```
 
 Advanced: `useWorkflow()` (inside the tree) exposes the graph, `dispatch`,
@@ -319,27 +388,28 @@ surfaces.
 
 ## Props reference
 
-| Prop | Type | Notes |
-| --- | --- | --- |
-| `nodeTypes` | `NodeTypeDef[]` | **Required.** Your registered kinds. |
-| `graph` | `Graph` | Controlled graph (pair with `onGraphChange`). |
-| `onGraphChange` | `(g: Graph) => void` | Fired on every edit. |
-| `defaultGraph` | `Graph` | Uncontrolled initial graph. |
-| `translate` | `(key, vars?) => ReactNode` | Chrome + `descriptionKey` translator. |
-| `issues` | `Issue[]` | Render-only validation (pass a stable ref). |
-| `validating` | `boolean` | Show "rechecking" while issues are stale/in-flight. |
-| `readOnly` | `boolean` | Disable editing; palette hidden. |
-| `showPalette` | `boolean` | Default `true`. |
-| `onSelectionChange` | `(sel \| null) => void` | Selection changed (node/edge/deselect). |
-| `onNodeClick` / `onEdgeClick` | `(node) / (edge) => void` | Raw click convenience. |
-| `onArrange` | `(g: Graph) => void` | After one-click auto-arrange. |
-| `onHistoryNavigate` | `(g: Graph) => void` | After undo/redo. |
-| `children` | `ReactNode` | Canvas overlay slot (mount `<NodeInspector>` here). |
-| `footer` | `ReactNode` | Slot below the canvas. |
-| `categoryTokens` | `CategoryTokenMap` | Override category → color tokens. |
-| `hostBridge` | `unknown` | Opaque host data for inspectors. |
-| `minHeight` | `string \| number` | Default `'500px'`. |
-| `onIssuesChange` | `(issues) => void` | Notified when the issues ref changes. |
+| Prop                          | Type                        | Notes                                               |
+| ----------------------------- | --------------------------- | --------------------------------------------------- |
+| `nodeTypes`                   | `NodeTypeDef[]`             | **Required.** Your registered kinds.                |
+| `graph`                       | `Graph`                     | Controlled graph (pair with `onGraphChange`).       |
+| `onGraphChange`               | `(g: Graph) => void`        | Fired on every edit.                                |
+| `defaultGraph`                | `Graph`                     | Uncontrolled initial graph.                         |
+| `translate`                   | `(key, vars?) => ReactNode` | Chrome + `descriptionKey` translator.               |
+| `issues`                      | `Issue[]`                   | Render-only validation (pass a stable ref).         |
+| `validating`                  | `boolean`                   | Show "rechecking" while issues are stale/in-flight. |
+| `readOnly`                    | `boolean`                   | Disable editing; palette hidden.                    |
+| `showPalette`                 | `boolean`                   | Default `true`.                                     |
+| `onSelectionChange`           | `(sel \| null) => void`     | Selection changed (node/edge/deselect).             |
+| `onNodeClick` / `onEdgeClick` | `(node) / (edge) => void`   | Raw click convenience.                              |
+| `onArrange`                   | `(g: Graph) => void`        | After one-click auto-arrange.                       |
+| `onHistoryNavigate`           | `(g: Graph) => void`        | After undo/redo.                                    |
+| `children`                    | `ReactNode`                 | Canvas overlay slot (mount `<NodeInspector>` here). |
+| `renderSelectedNodeToolbar`   | `(node) => ReactNode`       | Content beside the selected node (e.g. a "+").      |
+| `footer`                      | `ReactNode`                 | Slot below the canvas.                              |
+| `categoryTokens`              | `CategoryTokenMap`          | Override category → color tokens.                   |
+| `hostBridge`                  | `unknown`                   | Opaque host data for inspectors.                    |
+| `minHeight`                   | `string \| number`          | Default `'500px'`.                                  |
+| `onIssuesChange`              | `(issues) => void`          | Notified when the issues ref changes.               |
 
 `<NodeInspector>`: `dock?: 'left' | 'right'`, `renderEdgeDrawer?: ComponentType<EdgeDrawerRenderProps>`.
 

package/src/components/Workflow/Workflow.translations.json

@@ -109,4 +109,4 @@
     "en": "Create node",
     "ja": "ノードを追加"
   }
-}
+}

package/src/components/Workflow/Workflow.tsx

@@ -36,6 +36,7 @@ export function Workflow({
   onEdgeClick,
   onSelectionChange,
   onIssuesChange,
+  renderSelectedNodeToolbar,
   footer,
   children,
   categoryTokens,
@@ -169,13 +170,14 @@ export function Workflow({
           showPalette={showPalette && !readOnly}
           onNodeClick={onNodeClick}
           onEdgeClick={onEdgeClick}
+          renderSelectedNodeToolbar={renderSelectedNodeToolbar}
         >
           {children}
         </Canvas>
         {footer ? (
           <Box
             borderTop="1px solid"
-            borderColor="slate.200"
+            borderColor="border.default"
             bg="bg.surface"
             px={4}
             py={2}

package/src/components/Workflow/Workflow.types.ts

@@ -443,6 +443,16 @@ export type WorkflowProps = {
    */
   children?: ReactNode;
 
+  /**
+   * Content rendered beside the selected node, on its exit (right) side — e.g.
+   * a "+" that adds a node after it via `useWorkflowActions().addNode`. Called
+   * with the selected node whenever one is selected; return `null` to show
+   * nothing. The library positions it in screen space (it keeps its size at
+   * any zoom) and renders it inside the editor, so the content may call
+   * `useWorkflow` / `useWorkflowActions`. Hosts never touch React Flow.
+   */
+  renderSelectedNodeToolbar?: (node: GraphNode) => ReactNode;
+
   /**
    * Notified whenever the issues array identity changes. Mostly a Storybook
    * convenience now that validation is owned entirely by the backend — prod

package/src/components/Workflow/canvas/Canvas/BranchLabelBadge.tsx

@@ -3,7 +3,7 @@
 import type { MouseEvent, ReactNode } from 'react';
 
 import { Badge } from '@/components/Badge';
-import { TbCheck, TbX } from '@/components/Icon';
+import { CheckIcon, CloseIcon } from '@/components/Icon';
 
 import type { EdgeLabelVariant } from './edgeLabelVariant';
 
@@ -51,18 +51,19 @@ export function BranchLabelBadge({
       boxShadow="sm"
       _dark={{
         boxShadow: '0 0 0 1px {colors.border.strong}',
-        // slate.300, not the semantically-equivalent bg.emphasized: Chakra
-        // resolves `bg.*` tokens referenced inside a nested condition to their
-        // BASE value (rendering the light-gray light-mode fill in dark mode);
-        // the slate ramp resolves correctly here. No upstream issue filed —
-        // verified via rendered-DOM probe, 2026-06-12.
-        bgColor: badgeVariant === 'neutral' ? 'slate.300' : undefined,
+        // neutral.5 (the 5.0 step the 4.x slate.300 aliases to), not the
+        // semantically-equivalent bg.emphasized: Chakra resolves `bg.*`
+        // tokens referenced inside a nested condition to their BASE value
+        // (rendering the light-gray light-mode fill in dark mode); the step
+        // scale resolves correctly here. No upstream issue filed — verified
+        // via rendered-DOM probe, 2026-06-12.
+        bgColor: badgeVariant === 'neutral' ? 'neutral.5' : undefined,
       }}
       cursor={onClick ? 'pointer' : 'default'}
       onClick={onClick}
     >
-      {variant === 'pass' ? <TbCheck boxSize="xs" aria-hidden /> : null}
-      {variant === 'fail' ? <TbX boxSize="xs" aria-hidden /> : null}
+      {variant === 'pass' ? <CheckIcon boxSize="xs" aria-hidden /> : null}
+      {variant === 'fail' ? <CloseIcon boxSize="xs" aria-hidden /> : null}
       {children}
     </Badge>
   );