@particle-academy/fancy-flow 0.33.3 → 0.35.0

package/dist/llm/vercel-ai.d.ts

@@ -1,6 +1,6 @@
 import { LanguageModel } from 'ai';
-import { a as LlmRouteRequest, L as LlmClient } from '../capabilities-BH7zmSQQ.js';
-import '../types-CMSrWVYM.js';
+import { a as LlmRouteRequest, L as LlmClient } from '../capabilities-CkhKj_U_.js';
+import '../types-sOmpCitB.js';
 import '@xyflow/react';
 
 /**

package/dist/registry/index.d.cts

@@ -1,12 +1,12 @@
-import { N as NodeKindDefinition, d as PortSpec } from '../types-DEmDSByY.cjs';
-export { C as ConfigField, g as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, L as LEGACY_PAUSE_PREFIXES, a as NodeCategory, h as NumberConfigField, b as PAUSE_PREFIX, P as PauseAwaiting, c as PauseSignal, R as RenderBodyContext, j as RepeaterConfigField, k as RepeaterRowField, S as SelectConfigField, l as SwitchConfigField, T as TextConfigField, m as TextareaConfigField, e as decodePause, f as encodePause, i as isPause, p as pauseForHuman } from '../types-DEmDSByY.cjs';
-import { P as PortDescriptor, a as FlowNode, N as NodeExecutor } from '../types-CMSrWVYM.cjs';
+import { d as NodeKindDefinition, j as PortSpec } from '../types-D8Dezh9v.cjs';
+export { a as ConfigField, q as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, L as LEGACY_PAUSE_PREFIXES, c as NodeCategory, r as NumberConfigField, h as PAUSE_PREFIX, P as PauseAwaiting, i as PauseSignal, R as RenderBodyContext, t as RepeaterConfigField, u as RepeaterRowField, w as SelectConfigField, x as SwitchConfigField, T as TextConfigField, y as TextareaConfigField, m as decodePause, n as encodePause, o as isPause, p as pauseForHuman } from '../types-D8Dezh9v.cjs';
+import { P as PortDescriptor, b as FlowNode, N as NodeExecutor } from '../types-sOmpCitB.cjs';
 import { Connection, Edge, NodeProps, NodeTypes } from '@xyflow/react';
-import { b as LlmRoute } from '../capabilities-BLOeLACV.cjs';
-export { C as CapabilityId, L as LlmClient, c as LlmRouteChoice, a as LlmRouteRequest, W as WorkflowResolution, d as WorkflowResolutionFailure, e as WorkflowResolver, f as capabilityStatus, g as getLlmClient, h as getWorkflowResolver, i as isResolutionFailure, r as registerLlmClient, j as registerWorkflowResolver } from '../capabilities-BLOeLACV.cjs';
+import { b as LlmRoute } from '../capabilities-BtJQTbnw.cjs';
+export { C as CapabilityId, L as LlmClient, c as LlmRouteChoice, a as LlmRouteRequest, W as WorkflowResolution, d as WorkflowResolutionFailure, e as WorkflowResolver, f as capabilityStatus, g as getLlmClient, h as getWorkflowResolver, i as isResolutionFailure, r as registerLlmClient, j as registerWorkflowResolver } from '../capabilities-BtJQTbnw.cjs';
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
-export { c as categoryAccent, d as defaultConfigFor, g as getNodeKind, k as kindIds, l as listNodeKinds, o as onNodeKindsChanged, r as registerNodeKind, a as resolveKindId, v as validateConfig } from '../registry-qv4gRiuQ.cjs';
+export { c as categoryAccent, d as defaultConfigFor, g as getNodeKind, k as kindIds, l as listNodeKinds, o as onNodeKindsChanged, r as registerNodeKind, a as resolveKindId, v as validateConfig } from '../registry-Ru5jIS5H.cjs';
 
 /**
  * Connection validation — the single rule that decides whether an edge between

package/dist/registry/index.d.ts

@@ -1,12 +1,12 @@
-import { N as NodeKindDefinition, d as PortSpec } from '../types-Bj_ZHwqG.js';
-export { C as ConfigField, g as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, L as LEGACY_PAUSE_PREFIXES, a as NodeCategory, h as NumberConfigField, b as PAUSE_PREFIX, P as PauseAwaiting, c as PauseSignal, R as RenderBodyContext, j as RepeaterConfigField, k as RepeaterRowField, S as SelectConfigField, l as SwitchConfigField, T as TextConfigField, m as TextareaConfigField, e as decodePause, f as encodePause, i as isPause, p as pauseForHuman } from '../types-Bj_ZHwqG.js';
-import { P as PortDescriptor, a as FlowNode, N as NodeExecutor } from '../types-CMSrWVYM.js';
+import { d as NodeKindDefinition, j as PortSpec } from '../types-D6lsIGoe.js';
+export { a as ConfigField, q as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, L as LEGACY_PAUSE_PREFIXES, c as NodeCategory, r as NumberConfigField, h as PAUSE_PREFIX, P as PauseAwaiting, i as PauseSignal, R as RenderBodyContext, t as RepeaterConfigField, u as RepeaterRowField, w as SelectConfigField, x as SwitchConfigField, T as TextConfigField, y as TextareaConfigField, m as decodePause, n as encodePause, o as isPause, p as pauseForHuman } from '../types-D6lsIGoe.js';
+import { P as PortDescriptor, b as FlowNode, N as NodeExecutor } from '../types-sOmpCitB.js';
 import { Connection, Edge, NodeProps, NodeTypes } from '@xyflow/react';
-import { b as LlmRoute } from '../capabilities-BH7zmSQQ.js';
-export { C as CapabilityId, L as LlmClient, c as LlmRouteChoice, a as LlmRouteRequest, W as WorkflowResolution, d as WorkflowResolutionFailure, e as WorkflowResolver, f as capabilityStatus, g as getLlmClient, h as getWorkflowResolver, i as isResolutionFailure, r as registerLlmClient, j as registerWorkflowResolver } from '../capabilities-BH7zmSQQ.js';
+import { b as LlmRoute } from '../capabilities-CkhKj_U_.js';
+export { C as CapabilityId, L as LlmClient, c as LlmRouteChoice, a as LlmRouteRequest, W as WorkflowResolution, d as WorkflowResolutionFailure, e as WorkflowResolver, f as capabilityStatus, g as getLlmClient, h as getWorkflowResolver, i as isResolutionFailure, r as registerLlmClient, j as registerWorkflowResolver } from '../capabilities-CkhKj_U_.js';
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
-export { c as categoryAccent, d as defaultConfigFor, g as getNodeKind, k as kindIds, l as listNodeKinds, o as onNodeKindsChanged, r as registerNodeKind, a as resolveKindId, v as validateConfig } from '../registry-Dd1Q66uP.js';
+export { c as categoryAccent, d as defaultConfigFor, g as getNodeKind, k as kindIds, l as listNodeKinds, o as onNodeKindsChanged, r as registerNodeKind, a as resolveKindId, v as validateConfig } from '../registry-Df2-bTXZ.js';
 
 /**
  * Connection validation — the single rule that decides whether an edge between

package/dist/{registry-Dd1Q66uP.d.ts → registry-Df2-bTXZ.d.ts}

@@ -1,4 +1,4 @@
-import { N as NodeKindDefinition } from './types-Bj_ZHwqG.js';
+import { d as NodeKindDefinition } from './types-D6lsIGoe.js';
 
 /**
  * registerNodeKind — install a node kind in the global registry. Returns

package/dist/{registry-qv4gRiuQ.d.cts → registry-Ru5jIS5H.d.cts}

@@ -1,4 +1,4 @@
-import { N as NodeKindDefinition } from './types-DEmDSByY.cjs';
+import { d as NodeKindDefinition } from './types-D8Dezh9v.cjs';
 
 /**
  * registerNodeKind — install a node kind in the global registry. Returns

package/dist/rich-input.cjs

@@ -28,7 +28,7 @@ function isPageDoc(value) {
   const v = value;
   return Array.isArray(v.sections) && typeof v.nodes === "object" && v.nodes !== null;
 }
-function useFancyCmsForRichInput(options = {}) {
+function registerFancyCmsForRichInput(options = {}) {
   return registerRichInputAdapter({
     FauxClient: reactFancy.FauxClient,
     // Render the page at a real desktop width and scale it down, rather than
@@ -47,10 +47,12 @@ function useFancyCmsForRichInput(options = {}) {
     })
   });
 }
-useFancyCmsForRichInput();
+registerFancyCmsForRichInput();
+var useFancyCmsForRichInput = registerFancyCmsForRichInput;
 
 exports.emptyRichInputDoc = emptyRichInputDoc;
 exports.isPageDoc = isPageDoc;
+exports.registerFancyCmsForRichInput = registerFancyCmsForRichInput;
 exports.useFancyCmsForRichInput = useFancyCmsForRichInput;
 //# sourceMappingURL=rich-input.cjs.map
 //# sourceMappingURL=rich-input.cjs.map

package/dist/rich-input.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/registry/rich-input.tsx","../src/rich-input.tsx"],"names":["emptyDoc","FauxClient","createElement","CmsPage","Editor"],"mappings":";;;;;;;;AA+CA,IAAI,OAAA,GAAmC,IAAA;AACvC,IAAM,SAAA,uBAAgB,GAAA,EAAgB;AAG/B,SAAS,yBAAyB,IAAA,EAAoC;AAC3E,EAAA,OAAA,GAAU,IAAA;AACV,EAAA,KAAA,MAAW,CAAA,IAAK,WAAW,CAAA,EAAE;AAC7B,EAAA,OAAO,MAAM;AACX,IAAA,IAAI,YAAY,IAAA,EAAM;AACpB,MAAA,OAAA,GAAU,IAAA;AACV,MAAA,KAAA,MAAW,CAAA,IAAK,WAAW,CAAA,EAAE;AAAA,IAC/B;AAAA,EACF,CAAA;AACF;;;ACvBO,SAAS,iBAAA,CAAkB,KAAK,YAAA,EAAuB;AAC5D,EAAA,OAAOA,oBAAS,EAAE,CAAA;AACpB;AAGO,SAAS,UAAU,KAAA,EAAkC;AAC1D,EAAA,IAAI,KAAA,KAAU,IAAA,IAAQ,OAAO,KAAA,KAAU,UAAU,OAAO,KAAA;AACxD,EAAA,MAAM,CAAA,GAAI,KAAA;AACV,EAAA,OAAO,KAAA,CAAM,OAAA,CAAQ,CAAA,CAAE,QAAQ,CAAA,IAAK,OAAO,CAAA,CAAE,KAAA,KAAU,QAAA,IAAY,CAAA,CAAE,KAAA,KAAU,IAAA;AACjF;AAQO,SAAS,uBAAA,CAAwB,OAAA,GAMpC,EAAC,EAAe;AAClB,EAAA,OAAO,wBAAA,CAAyB;AAAA,gBAC9BC,qBAAA;AAAA;AAAA;AAAA;AAAA,IAIA,UAAA,EAAY,EAAE,OAAA,EAAS,SAAA,EAAW,OAAO,IAAA,EAAM,KAAA,EAAO,KAAA,EAAO,IAAA,EAAM,IAAA,EAAK;AAAA;AAAA;AAAA,IAIxE,gBAAgB,CAAC,GAAA,KACf,SAAA,CAAU,GAAG,IACTC,mBAAA,CAAcC,kBAAA,EAAS,EAAE,GAAA,EAAK,UAAU,OAAA,CAAQ,QAAA,EAAU,MAAM,OAAA,CAAQ,IAAA,EAAM,CAAA,GAC9E,IAAA;AAAA;AAAA,IAGN,cAAc,CAAC,EAAE,OAAO,QAAA,EAAS,KAC/BD,oBAAcE,iBAAA,EAAQ;AAAA,MACpB,YAAA,EAAc,SAAA,CAAU,KAAK,CAAA,GAAI,QAAQ,iBAAA,EAAkB;AAAA,MAC3D,QAAA;AAAA,MACA,UAAU,OAAA,CAAQ,QAAA;AAAA,MAClB,MAAM,OAAA,CAAQ;AAAA,KACf;AAAA,GACJ,CAAA;AACH;AAEA,uBAAA,EAAwB","file":"rich-input.cjs","sourcesContent":["import type { ComponentType, ReactNode } from \"react\";\n\n/**\n * Rich user input — the injection point.\n *\n * `rich_user_input` pauses a run on a fully authored page (long-form content,\n * required reading + confirmation, multi-section forms) rather than a flat\n * field list. That page IS a fancy-cms document — fancy-flow defines no\n * document schema of its own and never re-implements one.\n *\n * The wiring ships in the box. Import the subpath once and the node lights up:\n *\n * ```ts\n * import \"@particle-academy/fancy-flow/rich-input\";\n * ```\n *\n * That module registers fancy-cms's `PageDoc` + `CmsPage` renderer + `Editor`\n * against this seam. It lives on a separate entry so `@particle-academy/\n * fancy-cms-ui` and `@particle-academy/react-fancy` stay OPTIONAL peers — most\n * flows never use a rich input, and a workflow editor should not drag a CMS\n * into every install.\n *\n * The seam stays public so a host can substitute a different document engine,\n * but that is the escape hatch, not the expected path.\n *\n * Until something registers, the node still registers and still round-trips\n * its config — it renders a \"how to enable\" body rather than an empty card.\n */\nexport type RichInputAdapter = {\n  /**\n   * react-fancy's `FauxClient` (or any component with the same shape) — a\n   * frame that mimics a browser window or device and scales its content down\n   * to fit. Used to preview the authored page inside the node card.\n   */\n  FauxClient?: ComponentType<any>;\n  /**\n   * Props for the frame — e.g. `{ variant: \"browser\", width: 1280, scale: \"fit\" }`\n   * so a full-width page renders at its real width and scales down into the\n   * node card instead of reflowing to a cramped layout that misrepresents it.\n   */\n  frameProps?: Record<string, unknown>;\n  /** Render the stored document read-only, for the in-node preview. */\n  renderDocument?: (doc: unknown) => ReactNode;\n  /** Editor mounted in the config panel via `renderDocumentField`. */\n  renderEditor?: (props: { value: unknown; onChange: (next: unknown) => void }) => ReactNode;\n};\n\nlet adapter: RichInputAdapter | null = null;\nconst listeners = new Set<() => void>();\n\n/** Install the host's document editor + preview frame. Returns an unregister fn. */\nexport function registerRichInputAdapter(next: RichInputAdapter): () => void {\n  adapter = next;\n  for (const l of listeners) l();\n  return () => {\n    if (adapter === next) {\n      adapter = null;\n      for (const l of listeners) l();\n    }\n  };\n}\n\n/** The registered adapter, or null when the host hasn't wired one. */\nexport function getRichInputAdapter(): RichInputAdapter | null {\n  return adapter;\n}\n\n/** True once a host has wired an adapter — i.e. the node is usable. */\nexport function isRichInputEnabled(): boolean {\n  return adapter !== null && (adapter.renderDocument !== undefined || adapter.renderEditor !== undefined);\n}\n\n/** Subscribe to adapter changes (so nodes re-render when it lands). */\nexport function onRichInputAdapterChanged(fn: () => void): () => void {\n  listeners.add(fn);\n  return () => listeners.delete(fn);\n}\n\n/**\n * RichInputPreview — the node card body. Shows the authored page inside a\n * FauxClient frame so an author can see, at a glance on the canvas, what the\n * person hitting this step will be looking at.\n *\n * Degrades in two steps rather than one: no adapter at all → install hint;\n * adapter but nothing authored yet → an empty frame with the step title. A\n * blank node body would read as \"broken\" in both cases.\n */\nexport function RichInputPreview({ config }: { config: Record<string, unknown> }) {\n  const a = getRichInputAdapter();\n  const title = typeof config.title === \"string\" && config.title.trim() !== \"\" ? config.title : \"Untitled step\";\n  const doc = config.document;\n\n  if (!a || (!a.renderDocument && !a.renderEditor)) {\n    return (\n      <div className=\"ff-rich-preview\">\n        <span className=\"ff-rich-preview__title\">{title}</span>\n        <div className=\"ff-rich-preview__unavailable\">\n          Add <code>@particle-academy/fancy-cms-ui</code> +{\" \"}\n          <code>@particle-academy/react-fancy</code>, then{\" \"}\n          <code>import \"@particle-academy/fancy-flow/rich-input\"</code>.\n        </div>\n      </div>\n    );\n  }\n\n  const body = doc === undefined || doc === null\n    ? <p className=\"ff-rich-preview__unavailable\">Nothing authored yet.</p>\n    : a.renderDocument?.(doc) ?? null;\n\n  const Frame = a.FauxClient;\n\n  return (\n    <div className=\"ff-rich-preview\">\n      <span className=\"ff-rich-preview__title\">{title}</span>\n      <div className=\"ff-rich-preview__frame\">\n        {Frame ? <Frame {...(a.frameProps ?? { variant: \"browser\" })}>{body}</Frame> : body}\n      </div>\n    </div>\n  );\n}\n","/**\n * `@particle-academy/fancy-flow/rich-input` — wires `rich_user_input` to the\n * real CMS.\n *\n * Import this entry once, anywhere in your app, and the node lights up:\n *\n * ```ts\n * import \"@particle-academy/fancy-flow/rich-input\";\n * ```\n *\n * ## Why this is a separate entry\n *\n * The document a rich input step shows IS a fancy-cms page — same `PageDoc`,\n * same renderer, same editor. fancy-flow declares no document schema of its\n * own and never re-implements one; duplicating the model would guarantee the\n * two drift, and a step authored in fancy-flow would stop being a thing\n * fancy-cms could open.\n *\n * But most flows never use a rich input, and a workflow editor should not drag\n * a CMS into every install. So the dependency lives HERE, on an opt-in\n * subpath, instead of in the main entry. `@particle-academy/fancy-cms-ui` and\n * `@particle-academy/react-fancy` are optional peers: required to import this\n * module, irrelevant if you never do.\n */\nimport { createElement } from \"react\";\nimport { CmsPage, Editor, emptyDoc, type PageDoc } from \"@particle-academy/fancy-cms-ui\";\nimport { FauxClient } from \"@particle-academy/react-fancy\";\nimport { registerRichInputAdapter } from \"./registry/rich-input\";\n\nexport type { PageDoc };\n\n/**\n * A blank page for a step that hasn't been authored yet.\n *\n * `Editor` takes a `defaultValue`, not a nullable doc — so a never-authored\n * step needs a real empty document to open into rather than a blank screen.\n */\nexport function emptyRichInputDoc(id = \"rich-input\"): PageDoc {\n  return emptyDoc(id);\n}\n\n/** True when a stored value is a fancy-cms page document. */\nexport function isPageDoc(value: unknown): value is PageDoc {\n  if (value === null || typeof value !== \"object\") return false;\n  const v = value as Partial<PageDoc>;\n  return Array.isArray(v.sections) && typeof v.nodes === \"object\" && v.nodes !== null;\n}\n\n/**\n * Register fancy-cms as the document engine for `rich_user_input`.\n *\n * Called automatically on import. Exported so a host can re-register after\n * swapping in a custom element registry, and so the call is testable.\n */\nexport function useFancyCmsForRichInput(options: {\n  /** Custom element registry — pass the SAME one you give `CmsPage` at runtime,\n   *  or the edit canvas renders your node types as blank placeholders. */\n  registry?: Parameters<typeof CmsPage>[0][\"registry\"];\n  /** Data context that `{ $bind }` props preview against. */\n  data?: Parameters<typeof CmsPage>[0][\"data\"];\n} = {}): () => void {\n  return registerRichInputAdapter({\n    FauxClient,\n    // Render the page at a real desktop width and scale it down, rather than\n    // letting it reflow into a card-sized viewport — a preview that reflows\n    // shows a layout the person hitting the step will never see.\n    frameProps: { variant: \"browser\", width: 1280, scale: \"fit\", dots: true },\n\n    // Preview: the CMS's own renderer, so the node card shows exactly what the\n    // person hitting this step will see. Styles are scoped by the frame.\n    renderDocument: (doc) =>\n      isPageDoc(doc)\n        ? createElement(CmsPage, { doc, registry: options.registry, data: options.data })\n        : null,\n\n    // Authoring: the CMS's own WYSIWYG editor, in the config panel.\n    renderEditor: ({ value, onChange }) =>\n      createElement(Editor, {\n        defaultValue: isPageDoc(value) ? value : emptyRichInputDoc(),\n        onChange: onChange as (doc: PageDoc) => void,\n        registry: options.registry,\n        data: options.data,\n      }),\n  });\n}\n\nuseFancyCmsForRichInput();\n"]}
+{"version":3,"sources":["../src/registry/rich-input.tsx","../src/rich-input.tsx"],"names":["emptyDoc","FauxClient","createElement","CmsPage","Editor"],"mappings":";;;;;;;;AA+CA,IAAI,OAAA,GAAmC,IAAA;AACvC,IAAM,SAAA,uBAAgB,GAAA,EAAgB;AAG/B,SAAS,yBAAyB,IAAA,EAAoC;AAC3E,EAAA,OAAA,GAAU,IAAA;AACV,EAAA,KAAA,MAAW,CAAA,IAAK,WAAW,CAAA,EAAE;AAC7B,EAAA,OAAO,MAAM;AACX,IAAA,IAAI,YAAY,IAAA,EAAM;AACpB,MAAA,OAAA,GAAU,IAAA;AACV,MAAA,KAAA,MAAW,CAAA,IAAK,WAAW,CAAA,EAAE;AAAA,IAC/B;AAAA,EACF,CAAA;AACF;;;ACvBO,SAAS,iBAAA,CAAkB,KAAK,YAAA,EAAuB;AAC5D,EAAA,OAAOA,oBAAS,EAAE,CAAA;AACpB;AAGO,SAAS,UAAU,KAAA,EAAkC;AAC1D,EAAA,IAAI,KAAA,KAAU,IAAA,IAAQ,OAAO,KAAA,KAAU,UAAU,OAAO,KAAA;AACxD,EAAA,MAAM,CAAA,GAAI,KAAA;AACV,EAAA,OAAO,KAAA,CAAM,OAAA,CAAQ,CAAA,CAAE,QAAQ,CAAA,IAAK,OAAO,CAAA,CAAE,KAAA,KAAU,QAAA,IAAY,CAAA,CAAE,KAAA,KAAU,IAAA;AACjF;AAQO,SAAS,4BAAA,CAA6B,OAAA,GAMzC,EAAC,EAAe;AAClB,EAAA,OAAO,wBAAA,CAAyB;AAAA,gBAC9BC,qBAAA;AAAA;AAAA;AAAA;AAAA,IAIA,UAAA,EAAY,EAAE,OAAA,EAAS,SAAA,EAAW,OAAO,IAAA,EAAM,KAAA,EAAO,KAAA,EAAO,IAAA,EAAM,IAAA,EAAK;AAAA;AAAA;AAAA,IAIxE,gBAAgB,CAAC,GAAA,KACf,SAAA,CAAU,GAAG,IACTC,mBAAA,CAAcC,kBAAA,EAAS,EAAE,GAAA,EAAK,UAAU,OAAA,CAAQ,QAAA,EAAU,MAAM,OAAA,CAAQ,IAAA,EAAM,CAAA,GAC9E,IAAA;AAAA;AAAA,IAGN,cAAc,CAAC,EAAE,OAAO,QAAA,EAAS,KAC/BD,oBAAcE,iBAAA,EAAQ;AAAA,MACpB,YAAA,EAAc,SAAA,CAAU,KAAK,CAAA,GAAI,QAAQ,iBAAA,EAAkB;AAAA,MAC3D,QAAA;AAAA,MACA,UAAU,OAAA,CAAQ,QAAA;AAAA,MAClB,MAAM,OAAA,CAAQ;AAAA,KACf;AAAA,GACJ,CAAA;AACH;AAEA,4BAAA,EAA6B;AAatB,IAAM,uBAAA,GAA0B","file":"rich-input.cjs","sourcesContent":["import type { ComponentType, ReactNode } from \"react\";\n\n/**\n * Rich user input — the injection point.\n *\n * `rich_user_input` pauses a run on a fully authored page (long-form content,\n * required reading + confirmation, multi-section forms) rather than a flat\n * field list. That page IS a fancy-cms document — fancy-flow defines no\n * document schema of its own and never re-implements one.\n *\n * The wiring ships in the box. Import the subpath once and the node lights up:\n *\n * ```ts\n * import \"@particle-academy/fancy-flow/rich-input\";\n * ```\n *\n * That module registers fancy-cms's `PageDoc` + `CmsPage` renderer + `Editor`\n * against this seam. It lives on a separate entry so `@particle-academy/\n * fancy-cms-ui` and `@particle-academy/react-fancy` stay OPTIONAL peers — most\n * flows never use a rich input, and a workflow editor should not drag a CMS\n * into every install.\n *\n * The seam stays public so a host can substitute a different document engine,\n * but that is the escape hatch, not the expected path.\n *\n * Until something registers, the node still registers and still round-trips\n * its config — it renders a \"how to enable\" body rather than an empty card.\n */\nexport type RichInputAdapter = {\n  /**\n   * react-fancy's `FauxClient` (or any component with the same shape) — a\n   * frame that mimics a browser window or device and scales its content down\n   * to fit. Used to preview the authored page inside the node card.\n   */\n  FauxClient?: ComponentType<any>;\n  /**\n   * Props for the frame — e.g. `{ variant: \"browser\", width: 1280, scale: \"fit\" }`\n   * so a full-width page renders at its real width and scales down into the\n   * node card instead of reflowing to a cramped layout that misrepresents it.\n   */\n  frameProps?: Record<string, unknown>;\n  /** Render the stored document read-only, for the in-node preview. */\n  renderDocument?: (doc: unknown) => ReactNode;\n  /** Editor mounted in the config panel via `renderDocumentField`. */\n  renderEditor?: (props: { value: unknown; onChange: (next: unknown) => void }) => ReactNode;\n};\n\nlet adapter: RichInputAdapter | null = null;\nconst listeners = new Set<() => void>();\n\n/** Install the host's document editor + preview frame. Returns an unregister fn. */\nexport function registerRichInputAdapter(next: RichInputAdapter): () => void {\n  adapter = next;\n  for (const l of listeners) l();\n  return () => {\n    if (adapter === next) {\n      adapter = null;\n      for (const l of listeners) l();\n    }\n  };\n}\n\n/** The registered adapter, or null when the host hasn't wired one. */\nexport function getRichInputAdapter(): RichInputAdapter | null {\n  return adapter;\n}\n\n/** True once a host has wired an adapter — i.e. the node is usable. */\nexport function isRichInputEnabled(): boolean {\n  return adapter !== null && (adapter.renderDocument !== undefined || adapter.renderEditor !== undefined);\n}\n\n/** Subscribe to adapter changes (so nodes re-render when it lands). */\nexport function onRichInputAdapterChanged(fn: () => void): () => void {\n  listeners.add(fn);\n  return () => listeners.delete(fn);\n}\n\n/**\n * RichInputPreview — the node card body. Shows the authored page inside a\n * FauxClient frame so an author can see, at a glance on the canvas, what the\n * person hitting this step will be looking at.\n *\n * Degrades in two steps rather than one: no adapter at all → install hint;\n * adapter but nothing authored yet → an empty frame with the step title. A\n * blank node body would read as \"broken\" in both cases.\n */\nexport function RichInputPreview({ config }: { config: Record<string, unknown> }) {\n  const a = getRichInputAdapter();\n  const title = typeof config.title === \"string\" && config.title.trim() !== \"\" ? config.title : \"Untitled step\";\n  const doc = config.document;\n\n  if (!a || (!a.renderDocument && !a.renderEditor)) {\n    return (\n      <div className=\"ff-rich-preview\">\n        <span className=\"ff-rich-preview__title\">{title}</span>\n        <div className=\"ff-rich-preview__unavailable\">\n          Add <code>@particle-academy/fancy-cms-ui</code> +{\" \"}\n          <code>@particle-academy/react-fancy</code>, then{\" \"}\n          <code>import \"@particle-academy/fancy-flow/rich-input\"</code>.\n        </div>\n      </div>\n    );\n  }\n\n  const body = doc === undefined || doc === null\n    ? <p className=\"ff-rich-preview__unavailable\">Nothing authored yet.</p>\n    : a.renderDocument?.(doc) ?? null;\n\n  const Frame = a.FauxClient;\n\n  return (\n    <div className=\"ff-rich-preview\">\n      <span className=\"ff-rich-preview__title\">{title}</span>\n      <div className=\"ff-rich-preview__frame\">\n        {Frame ? <Frame {...(a.frameProps ?? { variant: \"browser\" })}>{body}</Frame> : body}\n      </div>\n    </div>\n  );\n}\n","/**\n * `@particle-academy/fancy-flow/rich-input` — wires `rich_user_input` to the\n * real CMS.\n *\n * Import this entry once, anywhere in your app, and the node lights up:\n *\n * ```ts\n * import \"@particle-academy/fancy-flow/rich-input\";\n * ```\n *\n * ## Why this is a separate entry\n *\n * The document a rich input step shows IS a fancy-cms page — same `PageDoc`,\n * same renderer, same editor. fancy-flow declares no document schema of its\n * own and never re-implements one; duplicating the model would guarantee the\n * two drift, and a step authored in fancy-flow would stop being a thing\n * fancy-cms could open.\n *\n * But most flows never use a rich input, and a workflow editor should not drag\n * a CMS into every install. So the dependency lives HERE, on an opt-in\n * subpath, instead of in the main entry. `@particle-academy/fancy-cms-ui` and\n * `@particle-academy/react-fancy` are optional peers: required to import this\n * module, irrelevant if you never do.\n */\nimport { createElement } from \"react\";\nimport { CmsPage, Editor, emptyDoc, type PageDoc } from \"@particle-academy/fancy-cms-ui\";\nimport { FauxClient } from \"@particle-academy/react-fancy\";\nimport { registerRichInputAdapter } from \"./registry/rich-input\";\n\nexport type { PageDoc };\n\n/**\n * A blank page for a step that hasn't been authored yet.\n *\n * `Editor` takes a `defaultValue`, not a nullable doc — so a never-authored\n * step needs a real empty document to open into rather than a blank screen.\n */\nexport function emptyRichInputDoc(id = \"rich-input\"): PageDoc {\n  return emptyDoc(id);\n}\n\n/** True when a stored value is a fancy-cms page document. */\nexport function isPageDoc(value: unknown): value is PageDoc {\n  if (value === null || typeof value !== \"object\") return false;\n  const v = value as Partial<PageDoc>;\n  return Array.isArray(v.sections) && typeof v.nodes === \"object\" && v.nodes !== null;\n}\n\n/**\n * Register fancy-cms as the document engine for `rich_user_input`.\n *\n * Called automatically on import. Exported so a host can re-register after\n * swapping in a custom element registry, and so the call is testable.\n */\nexport function registerFancyCmsForRichInput(options: {\n  /** Custom element registry — pass the SAME one you give `CmsPage` at runtime,\n   *  or the edit canvas renders your node types as blank placeholders. */\n  registry?: Parameters<typeof CmsPage>[0][\"registry\"];\n  /** Data context that `{ $bind }` props preview against. */\n  data?: Parameters<typeof CmsPage>[0][\"data\"];\n} = {}): () => void {\n  return registerRichInputAdapter({\n    FauxClient,\n    // Render the page at a real desktop width and scale it down, rather than\n    // letting it reflow into a card-sized viewport — a preview that reflows\n    // shows a layout the person hitting the step will never see.\n    frameProps: { variant: \"browser\", width: 1280, scale: \"fit\", dots: true },\n\n    // Preview: the CMS's own renderer, so the node card shows exactly what the\n    // person hitting this step will see. Styles are scoped by the frame.\n    renderDocument: (doc) =>\n      isPageDoc(doc)\n        ? createElement(CmsPage, { doc, registry: options.registry, data: options.data })\n        : null,\n\n    // Authoring: the CMS's own WYSIWYG editor, in the config panel.\n    renderEditor: ({ value, onChange }) =>\n      createElement(Editor, {\n        defaultValue: isPageDoc(value) ? value : emptyRichInputDoc(),\n        onChange: onChange as (doc: PageDoc) => void,\n        registry: options.registry,\n        data: options.data,\n      }),\n  });\n}\n\nregisterFancyCmsForRichInput();\n\n/**\n * @deprecated Renamed to `registerFancyCmsForRichInput`. This alias still works\n * and will not be removed in 0.x.\n *\n * The `use` prefix was wrong: this registers a document engine and returns a\n * dispose function — it is not a React hook and calls none. React reserves\n * `use*` for hooks, and the name made `react-hooks/rules-of-hooks` report the\n * module-scope call on import as a hook called outside a component. A linter\n * being misled by a name is the mild version; a reader assuming hook rules\n * apply, or that it must be called during render, is the real cost.\n */\nexport const useFancyCmsForRichInput = registerFancyCmsForRichInput;\n"]}

package/dist/rich-input.d.cts

@@ -16,12 +16,24 @@ declare function isPageDoc(value: unknown): value is PageDoc;
  * Called automatically on import. Exported so a host can re-register after
  * swapping in a custom element registry, and so the call is testable.
  */
-declare function useFancyCmsForRichInput(options?: {
+declare function registerFancyCmsForRichInput(options?: {
     /** Custom element registry — pass the SAME one you give `CmsPage` at runtime,
      *  or the edit canvas renders your node types as blank placeholders. */
     registry?: Parameters<typeof CmsPage>[0]["registry"];
     /** Data context that `{ $bind }` props preview against. */
     data?: Parameters<typeof CmsPage>[0]["data"];
 }): () => void;
+/**
+ * @deprecated Renamed to `registerFancyCmsForRichInput`. This alias still works
+ * and will not be removed in 0.x.
+ *
+ * The `use` prefix was wrong: this registers a document engine and returns a
+ * dispose function — it is not a React hook and calls none. React reserves
+ * `use*` for hooks, and the name made `react-hooks/rules-of-hooks` report the
+ * module-scope call on import as a hook called outside a component. A linter
+ * being misled by a name is the mild version; a reader assuming hook rules
+ * apply, or that it must be called during render, is the real cost.
+ */
+declare const useFancyCmsForRichInput: typeof registerFancyCmsForRichInput;
 
-export { emptyRichInputDoc, isPageDoc, useFancyCmsForRichInput };
+export { emptyRichInputDoc, isPageDoc, registerFancyCmsForRichInput, useFancyCmsForRichInput };

package/dist/rich-input.d.ts

@@ -16,12 +16,24 @@ declare function isPageDoc(value: unknown): value is PageDoc;
  * Called automatically on import. Exported so a host can re-register after
  * swapping in a custom element registry, and so the call is testable.
  */
-declare function useFancyCmsForRichInput(options?: {
+declare function registerFancyCmsForRichInput(options?: {
     /** Custom element registry — pass the SAME one you give `CmsPage` at runtime,
      *  or the edit canvas renders your node types as blank placeholders. */
     registry?: Parameters<typeof CmsPage>[0]["registry"];
     /** Data context that `{ $bind }` props preview against. */
     data?: Parameters<typeof CmsPage>[0]["data"];
 }): () => void;
+/**
+ * @deprecated Renamed to `registerFancyCmsForRichInput`. This alias still works
+ * and will not be removed in 0.x.
+ *
+ * The `use` prefix was wrong: this registers a document engine and returns a
+ * dispose function — it is not a React hook and calls none. React reserves
+ * `use*` for hooks, and the name made `react-hooks/rules-of-hooks` report the
+ * module-scope call on import as a hook called outside a component. A linter
+ * being misled by a name is the mild version; a reader assuming hook rules
+ * apply, or that it must be called during render, is the real cost.
+ */
+declare const useFancyCmsForRichInput: typeof registerFancyCmsForRichInput;
 
-export { emptyRichInputDoc, isPageDoc, useFancyCmsForRichInput };
+export { emptyRichInputDoc, isPageDoc, registerFancyCmsForRichInput, useFancyCmsForRichInput };

package/dist/rich-input.js

@@ -11,7 +11,7 @@ function isPageDoc(value) {
   const v = value;
   return Array.isArray(v.sections) && typeof v.nodes === "object" && v.nodes !== null;
 }
-function useFancyCmsForRichInput(options = {}) {
+function registerFancyCmsForRichInput(options = {}) {
   return registerRichInputAdapter({
     FauxClient,
     // Render the page at a real desktop width and scale it down, rather than
@@ -30,8 +30,9 @@ function useFancyCmsForRichInput(options = {}) {
     })
   });
 }
-useFancyCmsForRichInput();
+registerFancyCmsForRichInput();
+var useFancyCmsForRichInput = registerFancyCmsForRichInput;
 
-export { emptyRichInputDoc, isPageDoc, useFancyCmsForRichInput };
+export { emptyRichInputDoc, isPageDoc, registerFancyCmsForRichInput, useFancyCmsForRichInput };
 //# sourceMappingURL=rich-input.js.map
 //# sourceMappingURL=rich-input.js.map

package/dist/rich-input.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/rich-input.tsx"],"names":[],"mappings":";;;;;AAqCO,SAAS,iBAAA,CAAkB,KAAK,YAAA,EAAuB;AAC5D,EAAA,OAAO,SAAS,EAAE,CAAA;AACpB;AAGO,SAAS,UAAU,KAAA,EAAkC;AAC1D,EAAA,IAAI,KAAA,KAAU,IAAA,IAAQ,OAAO,KAAA,KAAU,UAAU,OAAO,KAAA;AACxD,EAAA,MAAM,CAAA,GAAI,KAAA;AACV,EAAA,OAAO,KAAA,CAAM,OAAA,CAAQ,CAAA,CAAE,QAAQ,CAAA,IAAK,OAAO,CAAA,CAAE,KAAA,KAAU,QAAA,IAAY,CAAA,CAAE,KAAA,KAAU,IAAA;AACjF;AAQO,SAAS,uBAAA,CAAwB,OAAA,GAMpC,EAAC,EAAe;AAClB,EAAA,OAAO,wBAAA,CAAyB;AAAA,IAC9B,UAAA;AAAA;AAAA;AAAA;AAAA,IAIA,UAAA,EAAY,EAAE,OAAA,EAAS,SAAA,EAAW,OAAO,IAAA,EAAM,KAAA,EAAO,KAAA,EAAO,IAAA,EAAM,IAAA,EAAK;AAAA;AAAA;AAAA,IAIxE,gBAAgB,CAAC,GAAA,KACf,SAAA,CAAU,GAAG,IACT,aAAA,CAAc,OAAA,EAAS,EAAE,GAAA,EAAK,UAAU,OAAA,CAAQ,QAAA,EAAU,MAAM,OAAA,CAAQ,IAAA,EAAM,CAAA,GAC9E,IAAA;AAAA;AAAA,IAGN,cAAc,CAAC,EAAE,OAAO,QAAA,EAAS,KAC/B,cAAc,MAAA,EAAQ;AAAA,MACpB,YAAA,EAAc,SAAA,CAAU,KAAK,CAAA,GAAI,QAAQ,iBAAA,EAAkB;AAAA,MAC3D,QAAA;AAAA,MACA,UAAU,OAAA,CAAQ,QAAA;AAAA,MAClB,MAAM,OAAA,CAAQ;AAAA,KACf;AAAA,GACJ,CAAA;AACH;AAEA,uBAAA,EAAwB","file":"rich-input.js","sourcesContent":["/**\n * `@particle-academy/fancy-flow/rich-input` — wires `rich_user_input` to the\n * real CMS.\n *\n * Import this entry once, anywhere in your app, and the node lights up:\n *\n * ```ts\n * import \"@particle-academy/fancy-flow/rich-input\";\n * ```\n *\n * ## Why this is a separate entry\n *\n * The document a rich input step shows IS a fancy-cms page — same `PageDoc`,\n * same renderer, same editor. fancy-flow declares no document schema of its\n * own and never re-implements one; duplicating the model would guarantee the\n * two drift, and a step authored in fancy-flow would stop being a thing\n * fancy-cms could open.\n *\n * But most flows never use a rich input, and a workflow editor should not drag\n * a CMS into every install. So the dependency lives HERE, on an opt-in\n * subpath, instead of in the main entry. `@particle-academy/fancy-cms-ui` and\n * `@particle-academy/react-fancy` are optional peers: required to import this\n * module, irrelevant if you never do.\n */\nimport { createElement } from \"react\";\nimport { CmsPage, Editor, emptyDoc, type PageDoc } from \"@particle-academy/fancy-cms-ui\";\nimport { FauxClient } from \"@particle-academy/react-fancy\";\nimport { registerRichInputAdapter } from \"./registry/rich-input\";\n\nexport type { PageDoc };\n\n/**\n * A blank page for a step that hasn't been authored yet.\n *\n * `Editor` takes a `defaultValue`, not a nullable doc — so a never-authored\n * step needs a real empty document to open into rather than a blank screen.\n */\nexport function emptyRichInputDoc(id = \"rich-input\"): PageDoc {\n  return emptyDoc(id);\n}\n\n/** True when a stored value is a fancy-cms page document. */\nexport function isPageDoc(value: unknown): value is PageDoc {\n  if (value === null || typeof value !== \"object\") return false;\n  const v = value as Partial<PageDoc>;\n  return Array.isArray(v.sections) && typeof v.nodes === \"object\" && v.nodes !== null;\n}\n\n/**\n * Register fancy-cms as the document engine for `rich_user_input`.\n *\n * Called automatically on import. Exported so a host can re-register after\n * swapping in a custom element registry, and so the call is testable.\n */\nexport function useFancyCmsForRichInput(options: {\n  /** Custom element registry — pass the SAME one you give `CmsPage` at runtime,\n   *  or the edit canvas renders your node types as blank placeholders. */\n  registry?: Parameters<typeof CmsPage>[0][\"registry\"];\n  /** Data context that `{ $bind }` props preview against. */\n  data?: Parameters<typeof CmsPage>[0][\"data\"];\n} = {}): () => void {\n  return registerRichInputAdapter({\n    FauxClient,\n    // Render the page at a real desktop width and scale it down, rather than\n    // letting it reflow into a card-sized viewport — a preview that reflows\n    // shows a layout the person hitting the step will never see.\n    frameProps: { variant: \"browser\", width: 1280, scale: \"fit\", dots: true },\n\n    // Preview: the CMS's own renderer, so the node card shows exactly what the\n    // person hitting this step will see. Styles are scoped by the frame.\n    renderDocument: (doc) =>\n      isPageDoc(doc)\n        ? createElement(CmsPage, { doc, registry: options.registry, data: options.data })\n        : null,\n\n    // Authoring: the CMS's own WYSIWYG editor, in the config panel.\n    renderEditor: ({ value, onChange }) =>\n      createElement(Editor, {\n        defaultValue: isPageDoc(value) ? value : emptyRichInputDoc(),\n        onChange: onChange as (doc: PageDoc) => void,\n        registry: options.registry,\n        data: options.data,\n      }),\n  });\n}\n\nuseFancyCmsForRichInput();\n"]}
+{"version":3,"sources":["../src/rich-input.tsx"],"names":[],"mappings":";;;;;AAqCO,SAAS,iBAAA,CAAkB,KAAK,YAAA,EAAuB;AAC5D,EAAA,OAAO,SAAS,EAAE,CAAA;AACpB;AAGO,SAAS,UAAU,KAAA,EAAkC;AAC1D,EAAA,IAAI,KAAA,KAAU,IAAA,IAAQ,OAAO,KAAA,KAAU,UAAU,OAAO,KAAA;AACxD,EAAA,MAAM,CAAA,GAAI,KAAA;AACV,EAAA,OAAO,KAAA,CAAM,OAAA,CAAQ,CAAA,CAAE,QAAQ,CAAA,IAAK,OAAO,CAAA,CAAE,KAAA,KAAU,QAAA,IAAY,CAAA,CAAE,KAAA,KAAU,IAAA;AACjF;AAQO,SAAS,4BAAA,CAA6B,OAAA,GAMzC,EAAC,EAAe;AAClB,EAAA,OAAO,wBAAA,CAAyB;AAAA,IAC9B,UAAA;AAAA;AAAA;AAAA;AAAA,IAIA,UAAA,EAAY,EAAE,OAAA,EAAS,SAAA,EAAW,OAAO,IAAA,EAAM,KAAA,EAAO,KAAA,EAAO,IAAA,EAAM,IAAA,EAAK;AAAA;AAAA;AAAA,IAIxE,gBAAgB,CAAC,GAAA,KACf,SAAA,CAAU,GAAG,IACT,aAAA,CAAc,OAAA,EAAS,EAAE,GAAA,EAAK,UAAU,OAAA,CAAQ,QAAA,EAAU,MAAM,OAAA,CAAQ,IAAA,EAAM,CAAA,GAC9E,IAAA;AAAA;AAAA,IAGN,cAAc,CAAC,EAAE,OAAO,QAAA,EAAS,KAC/B,cAAc,MAAA,EAAQ;AAAA,MACpB,YAAA,EAAc,SAAA,CAAU,KAAK,CAAA,GAAI,QAAQ,iBAAA,EAAkB;AAAA,MAC3D,QAAA;AAAA,MACA,UAAU,OAAA,CAAQ,QAAA;AAAA,MAClB,MAAM,OAAA,CAAQ;AAAA,KACf;AAAA,GACJ,CAAA;AACH;AAEA,4BAAA,EAA6B;AAatB,IAAM,uBAAA,GAA0B","file":"rich-input.js","sourcesContent":["/**\n * `@particle-academy/fancy-flow/rich-input` — wires `rich_user_input` to the\n * real CMS.\n *\n * Import this entry once, anywhere in your app, and the node lights up:\n *\n * ```ts\n * import \"@particle-academy/fancy-flow/rich-input\";\n * ```\n *\n * ## Why this is a separate entry\n *\n * The document a rich input step shows IS a fancy-cms page — same `PageDoc`,\n * same renderer, same editor. fancy-flow declares no document schema of its\n * own and never re-implements one; duplicating the model would guarantee the\n * two drift, and a step authored in fancy-flow would stop being a thing\n * fancy-cms could open.\n *\n * But most flows never use a rich input, and a workflow editor should not drag\n * a CMS into every install. So the dependency lives HERE, on an opt-in\n * subpath, instead of in the main entry. `@particle-academy/fancy-cms-ui` and\n * `@particle-academy/react-fancy` are optional peers: required to import this\n * module, irrelevant if you never do.\n */\nimport { createElement } from \"react\";\nimport { CmsPage, Editor, emptyDoc, type PageDoc } from \"@particle-academy/fancy-cms-ui\";\nimport { FauxClient } from \"@particle-academy/react-fancy\";\nimport { registerRichInputAdapter } from \"./registry/rich-input\";\n\nexport type { PageDoc };\n\n/**\n * A blank page for a step that hasn't been authored yet.\n *\n * `Editor` takes a `defaultValue`, not a nullable doc — so a never-authored\n * step needs a real empty document to open into rather than a blank screen.\n */\nexport function emptyRichInputDoc(id = \"rich-input\"): PageDoc {\n  return emptyDoc(id);\n}\n\n/** True when a stored value is a fancy-cms page document. */\nexport function isPageDoc(value: unknown): value is PageDoc {\n  if (value === null || typeof value !== \"object\") return false;\n  const v = value as Partial<PageDoc>;\n  return Array.isArray(v.sections) && typeof v.nodes === \"object\" && v.nodes !== null;\n}\n\n/**\n * Register fancy-cms as the document engine for `rich_user_input`.\n *\n * Called automatically on import. Exported so a host can re-register after\n * swapping in a custom element registry, and so the call is testable.\n */\nexport function registerFancyCmsForRichInput(options: {\n  /** Custom element registry — pass the SAME one you give `CmsPage` at runtime,\n   *  or the edit canvas renders your node types as blank placeholders. */\n  registry?: Parameters<typeof CmsPage>[0][\"registry\"];\n  /** Data context that `{ $bind }` props preview against. */\n  data?: Parameters<typeof CmsPage>[0][\"data\"];\n} = {}): () => void {\n  return registerRichInputAdapter({\n    FauxClient,\n    // Render the page at a real desktop width and scale it down, rather than\n    // letting it reflow into a card-sized viewport — a preview that reflows\n    // shows a layout the person hitting the step will never see.\n    frameProps: { variant: \"browser\", width: 1280, scale: \"fit\", dots: true },\n\n    // Preview: the CMS's own renderer, so the node card shows exactly what the\n    // person hitting this step will see. Styles are scoped by the frame.\n    renderDocument: (doc) =>\n      isPageDoc(doc)\n        ? createElement(CmsPage, { doc, registry: options.registry, data: options.data })\n        : null,\n\n    // Authoring: the CMS's own WYSIWYG editor, in the config panel.\n    renderEditor: ({ value, onChange }) =>\n      createElement(Editor, {\n        defaultValue: isPageDoc(value) ? value : emptyRichInputDoc(),\n        onChange: onChange as (doc: PageDoc) => void,\n        registry: options.registry,\n        data: options.data,\n      }),\n  });\n}\n\nregisterFancyCmsForRichInput();\n\n/**\n * @deprecated Renamed to `registerFancyCmsForRichInput`. This alias still works\n * and will not be removed in 0.x.\n *\n * The `use` prefix was wrong: this registers a document engine and returns a\n * dispose function — it is not a React hook and calls none. React reserves\n * `use*` for hooks, and the name made `react-hooks/rules-of-hooks` report the\n * module-scope call on import as a hook called outside a component. A linter\n * being misled by a name is the mild version; a reader assuming hook rules\n * apply, or that it must be called during render, is the real cost.\n */\nexport const useFancyCmsForRichInput = registerFancyCmsForRichInput;\n"]}

package/dist/{run-cohort-DitsaYgS.d.cts → run-cohort-Bjv2ZU6g.d.cts}

@@ -1,4 +1,4 @@
-import { F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-CMSrWVYM.cjs';
+import { F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-sOmpCitB.cjs';
 
 type RunOptions = {
     /** Stop the run after this many ms. Default: no timeout. */

package/dist/{run-cohort-CV7EcwGG.d.ts → run-cohort-BnP6ErHi.d.ts}

@@ -1,4 +1,4 @@
-import { F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-CMSrWVYM.js';
+import { F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-sOmpCitB.js';
 
 type RunOptions = {
     /** Stop the run after this many ms. Default: no timeout. */

package/dist/runtime/index.d.cts

@@ -1,6 +1,6 @@
-import { d as RunResult, R as RunOptions } from '../run-cohort-DitsaYgS.cjs';
-export { C as CohortGuard, a as CohortOptions, b as CohortPolicy, c as CohortResult, r as runCohort, e as runFlow } from '../run-cohort-DitsaYgS.cjs';
-import { e as NodeRunStatus, F as FlowGraph, E as ExecutorRegistry, a as FlowNode, b as FlowEdge } from '../types-CMSrWVYM.cjs';
+import { d as RunResult, R as RunOptions } from '../run-cohort-Bjv2ZU6g.cjs';
+export { C as CohortGuard, a as CohortOptions, b as CohortPolicy, c as CohortResult, r as runCohort, e as runFlow } from '../run-cohort-Bjv2ZU6g.cjs';
+import { e as NodeRunStatus, F as FlowGraph, E as ExecutorRegistry, b as FlowNode, a as FlowEdge } from '../types-sOmpCitB.cjs';
 import { NodeChange, EdgeChange, Connection } from '@xyflow/react';
 
 type FlowRunFeedEntry = {

package/dist/runtime/index.d.ts

@@ -1,6 +1,6 @@
-import { d as RunResult, R as RunOptions } from '../run-cohort-CV7EcwGG.js';
-export { C as CohortGuard, a as CohortOptions, b as CohortPolicy, c as CohortResult, r as runCohort, e as runFlow } from '../run-cohort-CV7EcwGG.js';
-import { e as NodeRunStatus, F as FlowGraph, E as ExecutorRegistry, a as FlowNode, b as FlowEdge } from '../types-CMSrWVYM.js';
+import { d as RunResult, R as RunOptions } from '../run-cohort-BnP6ErHi.js';
+export { C as CohortGuard, a as CohortOptions, b as CohortPolicy, c as CohortResult, r as runCohort, e as runFlow } from '../run-cohort-BnP6ErHi.js';
+import { e as NodeRunStatus, F as FlowGraph, E as ExecutorRegistry, b as FlowNode, a as FlowEdge } from '../types-sOmpCitB.js';
 import { NodeChange, EdgeChange, Connection } from '@xyflow/react';
 
 type FlowRunFeedEntry = {

package/dist/schema/index.d.cts

@@ -1,4 +1,4 @@
-import { P as PortDescriptor, F as FlowGraph } from '../types-CMSrWVYM.cjs';
+import { P as PortDescriptor, F as FlowGraph } from '../types-sOmpCitB.cjs';
 import '@xyflow/react';
 
 /** Schema version. Bump on breaking shape changes; add migrations as needed. */

package/dist/schema/index.d.ts

@@ -1,4 +1,4 @@
-import { P as PortDescriptor, F as FlowGraph } from '../types-CMSrWVYM.js';
+import { P as PortDescriptor, F as FlowGraph } from '../types-sOmpCitB.js';
 import '@xyflow/react';
 
 /** Schema version. Bump on breaking shape changes; add migrations as needed. */

package/dist/{types-DEmDSByY.d.cts → types-D6lsIGoe.d.ts}

@@ -1,6 +1,6 @@
 import { ReactNode, ComponentType } from 'react';
 import { NodeProps } from '@xyflow/react';
-import { P as PortDescriptor, N as NodeExecutor, a as FlowNode } from './types-CMSrWVYM.cjs';
+import { P as PortDescriptor, N as NodeExecutor, b as FlowNode } from './types-sOmpCitB.js';
 
 /**
  * The human-pause contract.
@@ -97,6 +97,237 @@ declare function pauseForHuman(ctx: {
     abort: (reason?: string) => never;
 }, awaiting: PauseAwaiting, detail?: unknown): never;
 
+/**
+ * The node package manifest — what a marketplace node declares about itself.
+ *
+ * A node is not one artifact. It is a kind definition (palette entry, config
+ * schema, ports, renderer) plus an executor for EACH runtime the consumer runs.
+ * A package shipping only a TS executor is unusable to anyone executing on PHP,
+ * and without a manifest that is invisible until a run fails. Requested by the
+ * MOIC Suite consumer (fancy-flow#2 §2), who runs the editor in TS and executes
+ * in PHP and hit exactly this.
+ *
+ * The manifest is data, not code: the registry, the CLI, and the MCP all read
+ * it without executing anything a package author wrote.
+ *
+ * ## Why the engine range lives per runtime
+ *
+ * The first cut of this manifest carried ONE `fancyFlow` range, and it was
+ * wrong: the two engines version independently, so a single range cannot say
+ * "needs npm >=0.11 AND php >=0.5". A package supporting both runtimes would
+ * install cleanly against a host whose OTHER runtime was too old — the 0.9.0
+ * failure shape wearing a manifest. The range belongs inside each runtime.
+ */
+
+/** The current manifest schema version. Bump only on a breaking shape change. */
+declare const NODE_MANIFEST_SCHEMA_VERSION = 1;
+/**
+ * A runtime a node can implement.
+ *
+ * Open rather than a closed union — the PHP and Node twins are what exist
+ * today, but the point of a manifest is that a runtime we haven't written can
+ * declare itself without a release here.
+ */
+type NodeRuntimeId = "ts" | "php" | (string & {});
+/**
+ * How one runtime provides this node, and which engine version it needs.
+ *
+ * `files` are source directories, not a dependency: a node is **vendored**, so
+ * `fancy-cli add node` copies them into the project the way it copies a
+ * component's source. One node, one source, readable and editable in the app
+ * rather than hidden in `node_modules` or `vendor`.
+ *
+ * This spec covers a runtime's BACKEND only. The surface lives in the
+ * manifest's `ui`, because the editor is React on every host — a Laravel
+ * project needs the React kind and does not need the TypeScript executor.
+ */
+type NodeRuntimeSpec = {
+    /** This backend's source directories, relative to the node. */
+    files: string[];
+    /** Semver range of THIS runtime's engine. Required — see the module note. */
+    engine: string;
+};
+/**
+ * Whether a capability must be wired for the node to work at all.
+ *
+ * `required` is checked at AUTHOR time, not run time. The failure that hurts is
+ * a node that installs fine, authors fine, and silently no-ops during a run —
+ * the same silence as a routing bug. An editor can grey the node and say which
+ * capability the host never registered.
+ */
+type CapabilityRequirement = "required" | "optional";
+/**
+ * Whether a node is safe to run again.
+ *
+ * Durable runs RETRY. A node that writes needs to say so, or a host has to pick
+ * one retry policy for every node and get it wrong somewhere.
+ */
+type SideEffects = "none" | "idempotent" | "unsafe-to-replay";
+/**
+ * A Fancy suite package this node's source imports.
+ *
+ * Separate from a plain npm dependency because the suite is polyglot and
+ * vendorable: the same capability ships as an npm package, a Composer package,
+ * or source you copy in, and which of those a consumer wants depends on the
+ * host — so the node names the *package*, and the CLI offers the routes that
+ * exist. A bare `dependencies: ["@particle-academy/fancy-screens"]` can only
+ * ever offer `npm install`, which is the wrong answer in a Laravel app whose
+ * editor is vendored.
+ *
+ * ## No versions, deliberately
+ *
+ * Nothing here carries a range, and the validator rejects one. A pinned
+ * marketplace node freezes a consumer on an old surface: the suite ships
+ * additively and often, and a node that pinned `^0.4` at authoring time would
+ * be holding a project back a year later for a constraint nobody revisits.
+ * Compatibility is expressed where it can actually be checked — `runtimes[].engine`
+ * against the *engine*, which is the contract a node really depends on.
+ */
+type FancyDependency = {
+    /** Suite slug — what `/packages/<slug>` documents. */
+    package: string;
+    /** npm name, when the suite ships one. */
+    npm?: string;
+    /** Composer name, when the suite ships one. */
+    composer?: string;
+    /**
+     * Why the node needs it, in a few words.
+     *
+     * Printed at install. Without it the CLI can only present a bare name and a
+     * command, which reads as an unexplained demand for a second package.
+     */
+    reason?: string;
+    /** Whether the node fails without it, or merely does less. Defaults to required. */
+    requirement?: CapabilityRequirement;
+};
+type NodePackageManifest = {
+    /** Must equal `NODE_MANIFEST_SCHEMA_VERSION`. */
+    schemaVersion: number;
+    /** Package name, as installed (`@acme/fancy-flow-salesforce`). */
+    name: string;
+    /**
+     * The canonical kind id this package provides — namespaced, and the string
+     * that gets persisted into every document using it.
+     */
+    kind: string;
+    /**
+     * Previous ids this kind still answers to.
+     *
+     * Core renamed `llm_branch` to `llm_router` and kept every old id working.
+     * Third-party packages will rename too, and their documents break the same
+     * way core's would have — so packages get the same escape hatch, otherwise
+     * only first-party nodes can rename safely.
+     */
+    aliases?: string[];
+    /**
+     * Version of this node's CONFIG shape, independent of the document schema.
+     *
+     * A node's config evolves on its own clock. Without a declared version, every
+     * executor accretes hand-written read-fallbacks forever (MOIC carries one for
+     * `routes[].key` → `routes[].port`), because nothing canonicalises old config
+     * the way import canonicalises kind ids.
+     */
+    configVersion?: number;
+    /**
+     * The node's SURFACE — its React kind — as source directories.
+     *
+     * Copied whichever backend the consumer picks, because the editor is React on
+     * every host. Kept out of `runtimes` deliberately: fold the two together and
+     * a PHP project either loses its palette entry or gains a TypeScript executor
+     * it will never run.
+     */
+    ui?: string[];
+    /** Per-runtime backend source and engine ranges. */
+    runtimes: Partial<Record<NodeRuntimeId, NodeRuntimeSpec>>;
+    /**
+     * Host capabilities this node needs, and whether each is mandatory.
+     *
+     * Declared so the CLI and the editor can say what to wire BEFORE a run,
+     * rather than the node silently no-opping or crashing mid-run.
+     */
+    capabilities?: Record<string, CapabilityRequirement>;
+    /** Fancy suite packages this node's source imports. See {@link FancyDependency}. */
+    fancyDependencies?: FancyDependency[];
+    /**
+     * Path to this node's golden fixtures, relative to the package root.
+     *
+     * REQUIRED. Every runtime the package claims runs these same cases, which is
+     * what makes "behaves identically on both runtimes" verified rather than
+     * asserted. See `./fixtures`.
+     */
+    fixtures: string;
+    /**
+     * Declares the node halts for a person. Mirrors `NodeKindDefinition`.
+     *
+     * A host-planning fact, not a node internal: a parent that embeds workflows
+     * needs to reject a child that can pause, because a paused child wedges the
+     * parent — and discovering that at run time means watching a run park.
+     */
+    pausesForHuman?: PauseAwaiting;
+    /** Whether this node is safe to replay. See `SideEffects`. */
+    sideEffects?: SideEffects;
+    /** One-line summary — what `search_nodes` matches against. */
+    description?: string;
+    /**
+     * Assigned by the registry, never by the author. Present in a manifest being
+     * submitted for publication, it is a claim to a trust signal the author does
+     * not get to make.
+     */
+    verified?: boolean;
+};
+type ManifestProblem = {
+    level: "error" | "warning";
+    field: string;
+    message: string;
+};
+type ManifestValidation = {
+    /** True when there are no `error`-level problems. Warnings do not block. */
+    ok: boolean;
+    manifest?: NodePackageManifest;
+    problems: ManifestProblem[];
+};
+/**
+ * Validate a manifest read from disk or a registry.
+ *
+ * Returns every problem rather than throwing on the first, because an author
+ * fixing a package wants the whole list — a validator that reveals one error
+ * per run turns a five-minute fix into five round trips.
+ */
+declare function validateNodeManifest(input: unknown): ManifestValidation;
+/**
+ * Check a node against the runtimes a host executes on, and their versions.
+ *
+ * Two failures live here, and both are errors because the node genuinely
+ * cannot run: a runtime the package does not implement at all, and a runtime
+ * it implements against an engine newer than the host's.
+ *
+ * `engineVersions` is optional — pass what the host knows. An unchecked range
+ * is reported as a warning rather than passed over silently, because "we did
+ * not check" and "it is fine" must not look the same.
+ */
+declare function checkRuntimeSupport(manifest: Pick<NodePackageManifest, "kind" | "runtimes">, hostRuntimes: readonly string[], engineVersions?: Readonly<Record<string, string>>): ManifestProblem[];
+/**
+ * Minimal semver range check — `^x.y.z`, `~x.y.z`, `>=x.y.z`, `x.y.z`, `*`.
+ *
+ * Deliberately small: this runs in the CLI and in CI, and pulling a semver
+ * library into the engine for one comparison is not worth the dependency. It
+ * covers the forms a manifest actually uses; anything it cannot parse is
+ * treated as unsatisfied rather than silently passed, so an unparseable range
+ * fails loudly instead of waving a node through.
+ */
+declare function satisfiesRange(version: string, range: string): boolean;
+/**
+ * Check that every capability a node needs is wired.
+ *
+ * A `required` capability that is missing is an ERROR — that is the whole point
+ * of the requirement level. It is meant to be surfaced at author time, so an
+ * editor can grey the node and name what the host never registered, rather than
+ * the node installing cleanly and silently no-opping during a run.
+ *
+ * An `optional` one is a warning: the node still works, with less.
+ */
+declare function checkCapabilities(manifest: Pick<NodePackageManifest, "kind" | "capabilities">, available: Readonly<Record<string, boolean>>): ManifestProblem[];
+
 /** Categories used by the palette for grouping. */
 type NodeCategory = "trigger" | "logic" | "data" | "ai" | "io" | "human" | "output" | "layout" | "annotation" | "custom";
 /**
@@ -336,6 +567,24 @@ type NodeKindDefinition<TConfig = Record<string, unknown>, TIn = any, TOut = any
      * refuse to list a pausing node whose package never says so.
      */
     pausesForHuman?: PauseAwaiting;
+    /**
+     * Whether a node of this kind is safe to run twice.
+     *
+     * The same three values a marketplace manifest declares (see `SideEffects`),
+     * lifted onto the KIND so it is readable at run time. A manifest is install-
+     * time data; a durable runner needs this while deciding whether to retry, and
+     * cannot go and read a manifest to find out.
+     *
+     * `fancy-flow-php`'s per-node queue driver keys its retry policy on exactly
+     * this: an `unsafe-to-replay` node gets one attempt whatever `tries` says,
+     * because a retried `git_pr_open` opens a second pull request. This field is
+     * the TypeScript half of that contract — the twins declare the same kind
+     * metadata or they are not twins.
+     *
+     * Declaration only. Nothing here enforces it; a host's runner decides what to
+     * do with it, and the TS in-process runner currently does not retry at all.
+     */
+    sideEffects?: SideEffects;
     /**
      * Make nodes of this kind resizable via drag handles (xyflow NodeResizer).
      * `true` enables it with defaults; pass options to bound it. The resulting
@@ -374,4 +623,4 @@ type NodeKindDefinition<TConfig = Record<string, unknown>, TIn = any, TOut = any
     reactive?: boolean;
 };
 
-export { type ConfigField as C, type DocumentConfigField as D, type ExpressionConfigField as E, type JsonConfigField as J, type KeyValueConfigField as K, LEGACY_PAUSE_PREFIXES as L, type NodeKindDefinition as N, type PauseAwaiting as P, type RenderBodyContext as R, type SelectConfigField as S, type TextConfigField as T, type NodeCategory as a, PAUSE_PREFIX as b, type PauseSignal as c, type PortSpec as d, decodePause as e, encodePause as f, type CredentialConfigField as g, type NumberConfigField as h, isPause as i, type RepeaterConfigField as j, type RepeaterRowField as k, type SwitchConfigField as l, type TextareaConfigField as m, pauseForHuman as p };
+export { type CapabilityRequirement as C, type DocumentConfigField as D, type ExpressionConfigField as E, type JsonConfigField as J, type KeyValueConfigField as K, LEGACY_PAUSE_PREFIXES as L, type ManifestProblem as M, NODE_MANIFEST_SCHEMA_VERSION as N, type PauseAwaiting as P, type RenderBodyContext as R, type SideEffects as S, type TextConfigField as T, type ConfigField as a, type ManifestValidation as b, type NodeCategory as c, type NodeKindDefinition as d, type NodePackageManifest as e, type NodeRuntimeId as f, type NodeRuntimeSpec as g, PAUSE_PREFIX as h, type PauseSignal as i, type PortSpec as j, checkCapabilities as k, checkRuntimeSupport as l, decodePause as m, encodePause as n, isPause as o, pauseForHuman as p, type CredentialConfigField as q, type NumberConfigField as r, satisfiesRange as s, type RepeaterConfigField as t, type RepeaterRowField as u, validateNodeManifest as v, type SelectConfigField as w, type SwitchConfigField as x, type TextareaConfigField as y };