feat(docs): render workflow previews with the shared editor renderer (#5277)

* chore(workflow-renderer): declare @sim/emcn dep + wire the package into docs

Adds the missing @sim/emcn peer/dev dependency to @sim/workflow-renderer (it imports @sim/emcn in every View but resolved only via workspace hoisting). Wires apps/docs to consume @sim/workflow-renderer (dependency, transpilePackages, Tailwind @source) and adds remark-breaks (pulled transitively via the barrel's NoteBlockView export) — mirroring the @sim/emcn integration. Foundation for migrating the docs workflow-preview fork onto the shared Views. Build resolves the package/@source/remark-breaks cleanly.

* feat(docs): render loop/parallel containers with the shared SubflowNodeView

Replaces the forked PreviewContainerNode with a thin DocsContainerNode that maps the static preview data to SubflowNodeView's read-only (isPreview) props — no stores or hooks. Adds the block size to the preview node data so the view can size itself, and corrects the parallel example's start-edge handle id to 'parallel-start-source' (the view derives the handle id from kind). Deletes preview-container-node.tsx. Container colors/icons are now owned by the shared view (loop=blue, parallel=yellow).

* feat(docs): render block nodes with the shared WorkflowBlockView

Replaces the forked PreviewBlockNode with a thin DocsBlockNode that maps the static preview data to WorkflowBlockView's props — store-free, builds the subblock rows (condition/router Context+routes/default + tools + error) via SubBlockRowView, strips branch-id prefixes so the view's regenerated handle ids match, remaps router->router_v2, and keeps the framer-motion dim/stagger wrapper. Promotes resolveIcon into block-icons.tsx, adds the --workflow-edge token to docs global.css, deletes preview-block-node.tsx. The canvas diagrams now render with the real editor's view.

* refactor(workflow-renderer): make editor-only WorkflowBlockView props optional

The child-deploy, schedule, and webhook badge props (and their callbacks) only matter in the editor. Mark them optional and optional-chain the three callbacks so read-only consumers (docs, academy) can omit the whole group instead of passing ~18 explicit off-values. The editor still passes them, so its behavior is byte-identical (verified: apps/sim type-check clean). DocsBlockNode drops the off-props.

* feat(docs): replace how-it-runs static diagrams with live WorkflowPreview

Swaps the four static PNGs on the how-it-runs page for live, app-styled WorkflowPreview diagrams (concurrency, combination, condition+router branching, error path). Adds the four example workflows and renders error-port edges red to match the editor. The English page only; the translated execution/basics pages keep the PNGs.

* refactor(workflow-renderer): the view owns condition/router/error rows

Both the editor container and the docs adapter hand-built the condition/router/error summary rows in an order that had to stay in lockstep with the view's absolute handle-offset math — a three-way coupling with nothing enforcing it. The view now renders those rows itself from the conditionRows/routerRows it already receives (plus a routerContextValue prop for the router's Context row), so row order and handle geometry live together in one place. Both containers pass only data and their non-branch rows.

Editor is byte-identical: getDisplayValue moves to where conditionRows/routerRows are built; the no-subBlock SubBlockRow path is already an exact SubBlockRowView(title, value) passthrough; the error row stays gated on shouldShowDefaultHandles. Verified apps/sim type-check clean. Docs now also renders the error row on condition/router blocks, which the real editor already did (shouldShowDefaultHandles is true for them) — an alignment fix.

* refactor(docs): drop the parallel --wp-* token layer for the app/emcn tokens

The workflow-preview ran a 25-token --wp-* mirror (22 were pure aliases of app tokens docs already defines) plus a .wp-scope wrapper class. Replaces every var(--wp-X) with its canonical app/emcn token (--wp-edge->--workflow-edge, --wp-highlight->--brand-secondary, badges->--badge-*, etc.), adds the one missing token (--divider), and deletes the .wp-scope blocks + class. Visually identical (aliases resolve to the same values); the preview now inherits the same design tokens as the shared views and the rest of the app instead of a hand-rolled parallel set.

* refactor(docs): adopt emcn Badge + dedup resolveIcon in workflow-preview

output-bundle's hand-rolled type badge (BADGE_COLORS + a styled span) becomes the emcn Badge (its green/blue/orange/purple/gray variants use the identical --badge-* tokens). resolveIcon, which had three copies, is now imported once from block-icons by output-bundle and block-inspector.

* refactor(docs): rebuild the preview inspector on emcn chip primitives

The lightbox inspector was a hand-rolled facsimile (raw divs + a CONTROL class string + inline dashed borders). It now composes from the same @sim/emcn primitives the live editor's sub-block controls wrap — ChipSelect/ChipInput/ChipTextarea(viewOnly)/ChipSwitch/ChipTag/FieldDivider/Label — so it reads as the real editor panel, fed example data (read-only, full opacity via readOnly/viewOnly, not greyed). Slider stays minimal (no emcn equivalent) but on app tokens. Props API and embedded/standalone modes unchanged.

* refactor(docs): render the block-reference hero through the shared View

Retires the hand-rolled BlockCard (a parallel reimplementation of WorkflowBlockView) and the BlockDisplaySpec data model. Each block hero is now a single-block PreviewWorkflow (block-display-workflows.ts) rendered through the same toReactFlowElements -> DocsBlockNode -> WorkflowBlockView pipeline as the diagrams, mounted in a minimal fitView ReactFlow (maxZoom 1.3, no canvas chrome). A single block can no longer drift from the canvas.

* fix(docs): define sim's type scale + align the preview inspector to the editor

Docs Tailwind v4 never defined sim's custom font sizes (text-small/caption/md/micro), so emcn components (Label, Badge, the shared views) fell back to inherited sizes — the inspector labels rendered huge. Adds the type scale to the docs @theme. Also aligns the inspector header to the real editor panel (surface-4 bar, size-[18px] rounded-sm icon, text-sm name) and removes the Connections section (and its now-dead prop/wiring).

* fix(docs): inspector shows the full field list + dragged positions persist

Inspector: shows the block type's full field list (from the reference data) with the example's values overlaid, so it reads like the editor panel instead of only the canvas summary rows. Drag: selecting another block no longer relayouts the canvas — node positions the viewer dragged are preserved across highlight/selection changes (only a different workflow relayouts).

* feat(docs): highlight <> references + env vars; hide Ask AI over the lightbox; respace blocks

Inspector text fields render the value with <...> block references and {{...}} environment variables highlighted in brand-secondary (a lean read-only port of the editor's formatDisplayText), in the canonical chip field chrome. The floating Ask AI widget is hidden while a preview lightbox is open. Plus the example-data respacing so the editor-faithful Error row no longer makes stacked blocks overlap.

* fix(docs): make per-type field templates match the real block registry

Audited every block type's field list (the source the inspector + block-reference heroes render) against apps/sim/blocks/blocks/*. Corrected drift to the registry's default-visible fields, titles, and order: agent gains Temperature; router gains Model; wait gains Async; schedule rewritten (default is Daily, not minutes); webhook_trigger expanded to its real default-visible set; human_in_the_loop notification title fixed. Provider-credential and advanced-mode fields stay hidden, matching the editor. Canvas diagrams keep their clean curated rows; the inspector now shows the full, real field list per the chosen clean-canvas/full-inspector split.

* improvement(docs): taller default preview height so respaced diagrams aren't shrunk

Bumps the default WorkflowPreview height 260->300 (the respaced, editor-faithful blocks are taller, so fitView was shrinking diagrams that relied on the default). The tall how-it-runs routing diagram gets 400.

* improvement(docs): zoomable inline preview + taller default + themed controls

The inline preview is now zoomable outside the lightbox: adds react-flow zoom/fit Controls (themed to the dark canvas chrome) and enables pinch-zoom, while keeping scroll-zoom off so the page still scrolls over the diagram. Pan-drag and click-block-to-inspect already worked. Default height 300->340.

* improvement(docs): click canvas to expand; click empty lightbox to deselect

Clicking the inline preview canvas opens the full lightbox; clicking empty space in the lightbox clears the selection, matching the real editor.

* improvement(docs): reveal inline zoom controls on hover only

The always-visible zoom controls felt heavy on the inline preview; they now fade in on hover (matching the expand button) and stay visible in the lightbox.

* improvement(docs): drop zoom controls on the inline preview

Inline preview keeps pinch-zoom, pan, drag, and click-to-expand; zoom buttons stay in the lightbox only.

* improvement(docs): remove zoom controls from the lightbox too

Both previews zoom via scroll/pinch and pan via drag; no on-canvas zoom buttons. Drops the Controls import and its theming CSS.

* improvement(docs): match the real canvas — flat background + editor edge geometry

Closes the last faithfulness gaps the audit found: removes the dot grid (the real editor hides its background — flat bg), aligns PreviewEdge to the editor's smoothstep math (borderRadius 8, offset 30) and 2px stroke (default + error edges), the selection ring to 1.75px, and minZoom to 0.1. Structural parity (blocks/handles/containers/colors/tokens) was already shared. Kept PreviewEdge rather than swapping to WorkflowEdgeView, which would clobber the docs-only highlight/dim/animate for no visual gain.

* improvement(docs): rebrand the docs assistant as 'Ask Sim', styled like the real chat input

Renames the floating assistant from 'Ask AI' to 'Ask Sim' (matching the platform's voice — you talk to Sim) and restyles the composer to mirror the home chat input: a rounded-2xl bordered field with the toolbar inside, and the same 28px circular send/stop button (the home's exact active/disabled colors + white/black arrow). Updates the lightbox hide-selector to the new label.

* improvement(docs): match Ask Sim message styling to the mothership chat

Aligns the user bubble (rounded-[16px] surface-5, text-base/primary, leading-23, max-w-85%) and the assistant markdown (text-base, 600 headings/strong, text-primary dashed-underline links, surface-5 code blocks) to the real mothership chat's user-message + chat-content treatment, instead of the prior generic text-sm rendering. The composer already mirrors the home user-input (rounded-2xl field + 28px circular send button).

* improvement(docs): compact single-row Ask Sim composer

The two-row layout left a tall dead gap (the docs widget has no toolbar buttons to fill the second row). The composer is now a single row — textarea with the circular send button inline — so it sits at the natural input height.

* fix(docs): pass the router Context value to the shared view

DocsBlockNode never set routerContextValue, so the view (which renders the router's Context row from that prop, not from rows) showed a blank Context even when the preview data authored a value like <start.input>. Extract it from the block's Context row and pass it through.

* fix(docs): don't apply a block-type field template that doesn't match the block

inspectorFieldsFor keyed the full field template purely off block.type, but some types are reused across roles (a table action block vs the table trigger, a webhook trigger vs the webhook action), so the wrong template was applied. Only use the template when the block's authored rows are actually a subset of it; otherwise fall back to the block's own rows.

* fix(docs): connect preview edges to subflow container handles

toReactFlowElements hardcoded targetHandle to 'target' and defaulted source handles to 'source', but Loop/Parallel containers (SubflowNodeView) expose a 'loop-end-source'/'parallel-end-source' output handle and a left input handle with no id. Edges into and out of containers therefore failed to connect. Resolve each edge end to the block's real handle based on whether it's a container.

* fix(docs): don't expand the inspector template for blocks with no rows

block.rows.every(...) is vacuously true for an empty rows array, so a block defined only by branches (e.g. a router in ROUTING_WORKFLOW) inherited the type template's invented field defaults. Require non-empty authored rows before applying the template.

* fix(docs): render blank branch/router-context values as '-' like the editor

The editor maps condition/router branch values and the router Context through getDisplayValue, which renders '-' for a blank value. DocsBlockNode mapped them to an empty string, so else branches and unset routes looked blank instead of matching the editor. Mirror getDisplayValue's empty-value handling.

* fix(docs): show '-' for blank inspector branch values, matching the canvas

inspectorFieldsFor passed raw branch.value into the lightbox branch fields, so an unset else route read blank in the inspector while DocsBlockNode (and the editor's getDisplayValue) render '-' on the canvas. Normalize the same way; drop the now-redundant placeholder.

Author: waleedlatif1

apps/docs/app/global.css

@@ -3,6 +3,7 @@
 @import "fumadocs-ui/css/preset.css";
 @import "fumadocs-openapi/css/preset.css";
 @source "../../../packages/emcn/src";
+@source "../../../packages/workflow-renderer/src";
 
 /* Prevent overscroll bounce effect on the page */
 html,
@@ -19,6 +20,20 @@ body {
 
 @theme {
   --color-fd-primary: var(--color-fd-foreground);
+  /* Sim's custom type scale — emcn components (Label, Badge, the shared block
+     views) use these names, so they must resolve here or text falls back to the
+     inherited size. Mirrors apps/sim/tailwind.config.ts. */
+  --text-micro: 10px;
+  --text-xs: 11px;
+  --text-caption: 12px;
+  --text-small: 13px;
+  --text-base: 15px;
+  --text-md: 16px;
+}
+
+/* Hide the floating Ask Sim widget while a workflow-preview lightbox is open. */
+body.wp-lightbox-open [aria-label="Ask Sim"] {
+  display: none;
 }
 
 /* Pure white light mode background */
@@ -42,6 +57,7 @@ body {
  */
 :root {
   --bg: #fefefe;
+  --workflow-edge: #e0e0e0;
   --surface-1: #fbfbfb;
   --surface-2: #ffffff;
   --surface-3: #f7f7f7;
@@ -51,6 +67,7 @@ body {
   --surface-active: #ececec;
   --border: #dedede;
   --border-1: #e0e0e0;
+  --divider: #ededed;
   --text-primary: #1a1a1a;
   --text-secondary: #525252;
   --text-tertiary: #5c5c5c;
@@ -91,6 +108,7 @@ body {
 
 .dark {
   --bg: #1b1b1b;
+  --workflow-edge: #454545;
   --surface-1: #1e1e1e;
   --surface-2: #232323;
   --surface-3: #242424;
@@ -100,6 +118,7 @@ body {
   --surface-active: #2c2c2c;
   --border: #333333;
   --border-1: #3d3d3d;
+  --divider: #393939;
   --text-primary: #e6e6e6;
   --text-secondary: #cccccc;
   --text-tertiary: #b3b3b3;
@@ -1661,56 +1680,6 @@ main article blockquote {
   box-shadow: none !important;
 }
 
-/* Workflow-preview theme scope. Values mirror the app's tokens in
-   apps/sim/app/_styles/globals.css (light from :root/.light, dark from .dark)
-   so the docs previews match the OG repository in both modes. */
-.wp-scope {
-  /* surfaces */
-  --wp-canvas: var(--bg);
-  --wp-panel: var(--surface-1);
-  --wp-surface: var(--surface-2);
-  --wp-header: var(--surface-3);
-  --wp-btn: var(--surface-4);
-  --wp-control: var(--surface-5);
-  --wp-active: var(--surface-active);
-  --wp-container-fill: rgba(0, 0, 0, 0.02);
-
-  /* borders */
-  --wp-border: var(--border);
-  --wp-border-1: var(--border-1);
-  --wp-chip-bg: var(--surface-5); /* ChipTag surface (light) */
-  --wp-chip-text: var(--text-body);
-  --wp-divider: #ededed; /* --divider */
-  --wp-edge: #e0e0e0; /* --workflow-edge */
-  --wp-highlight: #33b4ff; /* traced edge / highlighted output node */
-
-  /* text */
-  --wp-text: var(--text-primary);
-  --wp-text-2: var(--text-secondary);
-  --wp-text-3: var(--text-tertiary);
-  --wp-text-muted: var(--text-muted);
-  --wp-text-subtle: var(--text-subtle);
-
-  /* type badges (output inspector) */
-  --wp-badge-success-bg: var(--badge-success-bg);
-  --wp-badge-success-text: var(--badge-success-text);
-  --wp-badge-blue-bg: var(--badge-blue-bg);
-  --wp-badge-blue-text: var(--badge-blue-text);
-  --wp-badge-orange-bg: var(--badge-orange-bg);
-  --wp-badge-orange-text: var(--badge-orange-text);
-  --wp-badge-purple-bg: var(--badge-purple-bg);
-  --wp-badge-purple-text: var(--badge-purple-text);
-  --wp-badge-gray-bg: var(--badge-gray-bg);
-  --wp-badge-gray-text: var(--badge-gray-text);
-}
-
-.dark .wp-scope {
-  --wp-container-fill: rgba(255, 255, 255, 0.02);
-  --wp-chip-bg: var(--surface-4); /* ChipTag surface (dark) */
-  --wp-divider: #393939;
-  --wp-edge: #454545;
-}
-
 /* Tailwind v4 content sources */
 @source '../app/**/*.{js,ts,jsx,tsx,mdx}';
 @source '../components/**/*.{js,ts,jsx,tsx,mdx}';

apps/docs/components/ai/ask-ai.tsx

@@ -82,12 +82,12 @@ export function AskAI({ locale }: AskAIProps) {
       {!open && (
         <button
           type='button'
-          aria-label='Ask AI'
+          aria-label='Ask Sim'
           onClick={() => setOpen(true)}
           className='fixed right-4 bottom-4 z-50 flex h-11 items-center gap-1.5 rounded-full border border-[var(--border-1)] bg-[var(--surface-5)] px-4 font-season text-[var(--text-body)] text-sm shadow-[var(--shadow-medium)] transition-colors hover:bg-[var(--surface-active)] dark:bg-[var(--surface-4)]'
         >
           <MessageCircle className='size-[16px] text-[var(--text-icon)]' />
-          Ask AI
+          Ask Sim
         </button>
       )}
 
@@ -96,7 +96,7 @@ export function AskAI({ locale }: AskAIProps) {
           <div className='flex items-center justify-between border-[var(--border-1)] border-b px-4 py-3'>
             <span className='flex items-center gap-1.5 font-season text-[var(--text-body)] text-sm'>
               <MessageCircle className='size-[16px] text-[var(--text-icon)]' />
-              Ask AI
+              Ask Sim
             </span>
             <button
               type='button'
@@ -127,18 +127,27 @@ export function AskAI({ locale }: AskAIProps) {
                 <div
                   key={message.id}
                   className={cn(
-                    'flex flex-col gap-1',
+                    'flex flex-col gap-1.5',
                     message.role === 'user' ? 'items-end' : 'items-start'
                   )}
                 >
                   {message.role === 'user' ? (
-                    <div className='max-w-[90%] whitespace-pre-wrap rounded-lg bg-[var(--surface-active)] px-3 py-2 text-[var(--text-body)] text-sm'>
+                    <div className='max-w-[85%] whitespace-pre-wrap rounded-[16px] bg-[var(--surface-5)] px-3 py-2 text-[var(--text-primary)] text-base leading-[23px]'>
                       {text}
                     </div>
                   ) : (
-                    <div className='max-w-[90%] text-[var(--text-body)] text-sm'>
+                    <div className='max-w-full text-[var(--text-primary)] text-base'>
                       {text ? (
-                        <Streamdown className='space-y-2 text-sm leading-relaxed [&_a]:text-[var(--brand-accent)] [&_a]:underline [&_li]:my-0.5 [&_ol]:list-decimal [&_ol]:pl-5 [&_ul]:list-disc [&_ul]:pl-5'>
+                        <Streamdown
+                          className={cn(
+                            'space-y-3 text-[var(--text-primary)] text-base leading-relaxed',
+                            '[&_a]:text-[var(--text-primary)] [&_a]:underline [&_a]:decoration-dashed [&_a]:underline-offset-4',
+                            '[&_strong]:font-[600]',
+                            '[&_h1]:font-[600] [&_h2]:font-[600] [&_h3]:font-[600] [&_h4]:font-[600]',
+                            '[&_li]:my-1 [&_ol]:my-3 [&_ol]:list-decimal [&_ol]:pl-5 [&_ul]:my-3 [&_ul]:list-disc [&_ul]:pl-5',
+                            '[&_code]:font-mono [&_pre]:my-3 [&_pre]:overflow-x-auto [&_pre]:rounded-lg [&_pre]:bg-[var(--surface-5)] [&_pre]:p-3 [&_pre]:text-small'
+                          )}
+                        >
                           {text}
                         </Streamdown>
                       ) : isStreaming ? (
@@ -174,42 +183,46 @@ export function AskAI({ locale }: AskAIProps) {
             )}
           </div>
 
-          <form
-            onSubmit={handleSubmit}
-            className='flex items-end gap-2 border-[var(--border-1)] border-t px-3 py-3'
-          >
-            <textarea
-              value={input}
-              onChange={(event) => setInput(event.target.value)}
-              onKeyDown={(event) => {
-                if (event.key === 'Enter' && !event.shiftKey) {
-                  event.preventDefault()
-                  handleSubmit(event)
-                }
-              }}
-              rows={1}
-              placeholder='Ask a question…'
-              className='max-h-32 flex-1 resize-none bg-transparent font-season text-[var(--text-body)] text-sm outline-none placeholder:text-[var(--text-muted)]'
-            />
-            {isBusy ? (
-              <button
-                type='button'
-                aria-label='Stop'
-                onClick={() => stop()}
-                className='flex size-8 shrink-0 items-center justify-center rounded-lg bg-[var(--surface-active)] text-[var(--text-icon)]'
-              >
-                <Square className='size-[16px]' />
-              </button>
-            ) : (
-              <button
-                type='submit'
-                aria-label='Send'
-                disabled={!input.trim()}
-                className='flex size-8 shrink-0 items-center justify-center rounded-lg bg-[var(--text-primary)] text-[var(--text-inverse)] transition-opacity disabled:opacity-40 dark:bg-white dark:text-[var(--bg)]'
-              >
-                <ArrowUp className='size-[16px]' />
-              </button>
-            )}
+          <form onSubmit={handleSubmit} className='px-3 pb-3'>
+            <div className='flex items-end gap-2 rounded-2xl border border-[var(--border-1)] bg-white px-2.5 py-1.5 dark:bg-[var(--surface-5)]'>
+              <textarea
+                value={input}
+                onChange={(event) => setInput(event.target.value)}
+                onKeyDown={(event) => {
+                  if (event.key === 'Enter' && !event.shiftKey) {
+                    event.preventDefault()
+                    handleSubmit(event)
+                  }
+                }}
+                rows={1}
+                placeholder='Ask Sim about the docs…'
+                className='max-h-32 flex-1 resize-none bg-transparent py-1 font-season text-[var(--text-body)] text-sm outline-none placeholder:text-[var(--text-muted)]'
+              />
+              {isBusy ? (
+                <button
+                  type='button'
+                  aria-label='Stop'
+                  onClick={() => stop()}
+                  className='flex size-[28px] shrink-0 items-center justify-center rounded-full bg-[#383838] transition-colors hover:bg-[#575757] dark:bg-[#e0e0e0] dark:hover:bg-[#cfcfcf]'
+                >
+                  <Square className='size-[12px] fill-white text-white dark:fill-black dark:text-black' />
+                </button>
+              ) : (
+                <button
+                  type='submit'
+                  aria-label='Send'
+                  disabled={!input.trim()}
+                  className={cn(
+                    'flex size-[28px] shrink-0 items-center justify-center rounded-full transition-colors',
+                    input.trim()
+                      ? 'bg-[#383838] hover:bg-[#575757] dark:bg-[#e0e0e0] dark:hover:bg-[#cfcfcf]'
+                      : 'bg-[#808080]'
+                  )}
+                >
+                  <ArrowUp className='size-[16px] text-white dark:text-black' />
+                </button>
+              )}
+            </div>
           </form>
         </div>
       )}