feat(studio): first-class notify flow node in the Studio palette + inspector (#2808)

* feat(studio): first-class notify flow node in the Studio palette + inspector

The notify flow node (ADR-0012 — outbound notification via the messaging
service) is a live built-in but Studio had no static palette entry or config
editor: fieldsForNodeType('notify') returned [], so it was only authorable by
hand-editing JSON or when the running engine published its descriptor
(framework#1878 / framework#1895).

- NODE_PALETTE gains notify (Integration) + Bell icon, integration tone,
  canvas category, and a default-config seed (channels: ['inbox']).
- FLOW_NODE_CONFIG gains a notify entry mirroring the built-in descriptor:
  recipients/channels (stringList), title, message (textarea), topic,
  severity (select), and click-through target (sourceObject/sourceId/url),
  all under node.config.

Closes the last item of the designer-authoring-gaps issue (framework#1895).
Unit + DOM tested; browser dogfood recommended before merge.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CMaDBhnZEUu1fcw8Rvo6Yq

* test(studio): render-verify notify palette entry + inspector fields (#1895)

End-to-end Studio render check mounting the real NodePalette (with the
production NODE_PALETTE) and FlowNodeInspector: an author sees & picks
`notify` from the Integration group, and its inspector renders the config
fields (recipients/title/message/channels/topic/severity), writing edits
back under node.config. Browser-DOM stand-in for a live dogfood.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CMaDBhnZEUu1fcw8Rvo6Yq

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/flow-notify-studio-node.md

@@ -0,0 +1,25 @@
+---
+"@object-ui/app-shell": patch
+---
+
+feat(studio): first-class `notify` flow node in the Studio palette + inspector
+
+The `notify` flow node (ADR-0012 — outbound notification via the messaging
+service) is a live built-in with a server descriptor, but Studio had no static
+palette entry or config editor for it: `fieldsForNodeType('notify')` returned
+`[]`, so it was only authorable by hand-editing JSON or when the running engine
+happened to publish its descriptor (framework#1878 / framework#1895).
+
+- Added `notify` to `NODE_PALETTE` (Integration), with a Bell icon and the
+  integration tone, canvas category, and a sensible default-config seed
+  (`channels: ['inbox']`).
+- Added a `notify` entry to `FLOW_NODE_CONFIG` mirroring the built-in node's
+  descriptor keys: `recipients`/`channels` (stringList), `title`, `message`
+  (textarea), `topic`, `severity` (select info/warning/critical), and the
+  click-through target (`sourceObject`/`sourceId`/`url`) — all written under
+  `node.config`.
+
+Closes the last item of the designer-authoring-gaps issue (framework#1895).
+Unit + DOM tested (palette entry, config field kinds/paths, no inspector
+regression). A browser dogfood pass of authoring a notify node end-to-end is
+recommended before merge.

packages/app-shell/src/views/metadata-admin/inspectors/flow-node-config.test.ts

@@ -195,3 +195,34 @@ describe('loop / map collection is a template, not a CEL predicate', () => {
     expect(decisionCond.refMode).toBeUndefined();
   });
 });
+
+describe('notify node — first-class static config editor (#1895)', () => {
+  const fields = fieldsForNodeType('notify');
+  const ids = fields.map((f) => f.id);
+
+  it('surfaces the core notify config fields (was empty — no static editor before)', () => {
+    expect(fields.length).toBeGreaterThan(0);
+    expect(ids).toEqual(
+      expect.arrayContaining(['recipients', 'title', 'message', 'channels', 'topic', 'severity']),
+    );
+  });
+
+  it('models recipients + channels as stringList and message as textarea', () => {
+    expect(fields.find((f) => f.id === 'recipients')!.kind).toBe('stringList');
+    expect(fields.find((f) => f.id === 'channels')!.kind).toBe('stringList');
+    expect(fields.find((f) => f.id === 'message')!.kind).toBe('textarea');
+  });
+
+  it('writes each field under node.config (matching the built-in node descriptor)', () => {
+    for (const f of fields) {
+      expect(f.path[0]).toBe('config');
+    }
+    expect(fields.find((f) => f.id === 'title')!.path).toEqual(['config', 'title']);
+  });
+
+  it('offers the descriptor severity levels', () => {
+    const severity = fields.find((f) => f.id === 'severity')!;
+    expect(severity.kind).toBe('select');
+    expect(severity.options!.map((o) => o.value)).toEqual(['info', 'warning', 'critical']);
+  });
+});

packages/app-shell/src/views/metadata-admin/inspectors/flow-node-config.ts

@@ -667,6 +667,31 @@ const FLOW_NODE_CONFIG: Record<string, FlowConfigField[]> = {
     cfg('outputVariable', 'Output variable', 'text', { placeholder: 'subResult' }),
     { id: 'timeoutMs', path: ['timeoutMs'], label: 'Timeout (ms)', kind: 'number', placeholder: '60000' },
   ],
+  // `notify` — outbound notification (ADR-0012), dispatched via the messaging
+  // service. Config keys mirror the built-in node's server descriptor
+  // (service-automation `notify-node.ts` configSchema): title + ≥1 recipient
+  // are required at execute time; channels default to inbox. Surfaced here as a
+  // first-class static editor so the node is authorable offline, not only when
+  // the running engine publishes its descriptor (framework#1878/#1895).
+  notify: [
+    cfg('recipients', 'Recipients', 'stringList', { help: 'User id(s) / audience selector(s) to notify. At least one is required.' }),
+    cfg('title', 'Title', 'text', { placeholder: 'Your request was approved', help: 'Notification title (required).' }),
+    cfg('message', 'Message', 'textarea', { placeholder: 'Supports {var} template references.', help: 'Notification body.' }),
+    cfg('channels', 'Channels', 'stringList', { help: 'Channels to fan out to (default: inbox — e.g. inbox · email · push).' }),
+    cfg('topic', 'Topic', 'text', { placeholder: 'notify', help: 'Event topic (default: "notify").' }),
+    cfg('severity', 'Severity', 'select', {
+      options: [
+        { value: 'info', label: 'Info' },
+        { value: 'warning', label: 'Warning' },
+        { value: 'critical', label: 'Critical' },
+      ],
+      help: 'Notification severity.',
+    }),
+    // Click-through target (#2675): deep-link the notification to a record.
+    cfg('sourceObject', 'Link object', 'text', { placeholder: 'sys_approval_request', help: 'Object of the record the notification links to (requires Link record id).' }),
+    cfg('sourceId', 'Link record id', 'text', { help: 'Record id the notification links to (requires Link object).' }),
+    cfg('url', 'Click-through URL', 'text', { help: 'Explicit link; overrides the one synthesized from Link object/record.' }),
+  ],
   connector_action: [
     at('connectorConfig', 'connectorId', 'Connector', 'reference', { ref: { kind: 'connector' }, placeholder: 'slack · email · salesforce' }),
     // actionId is polymorphic on the chosen connector: the picker lists THAT

packages/app-shell/src/views/metadata-admin/inspectors/notify-node.dogfood.test.tsx

@@ -0,0 +1,109 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * notify flow node — end-to-end Studio render verification (#1895).
+ *
+ * Mounts the REAL user-facing components — the add-node palette popover and the
+ * schema-driven FlowNodeInspector — with the production `NODE_PALETTE` /
+ * `fieldsForNodeType`, and asserts an author can (1) see & pick `notify` from
+ * the Integration group and (2) edit its config fields. This is the browser-DOM
+ * stand-in for a live Studio dogfood (no live-app browser tooling in CI).
+ */
+
+import * as React from 'react';
+import { render, screen, fireEvent, cleanup, within } from '@testing-library/react';
+import { describe, it, expect, vi, beforeAll, afterEach } from 'vitest';
+import { NodePalette, NODE_PALETTE, nodeIcon } from '../previews/flow-canvas-parts';
+
+// The inspector's engine config-schema + object-field hooks are stubbed so it
+// falls back to the hardcoded `fieldsForNodeType` groups and resolves without a
+// network client (same pattern as FlowNodeInspector.test.tsx).
+vi.mock('../previews/useFlowNodePalette', () => ({
+  useActionConfigSchemas: () => ({}),
+  useFlowNodePalette: () => [],
+}));
+vi.mock('../previews/useObjectFields', () => ({
+  useObjectFields: () => ({ fields: [], loading: false, error: null }),
+}));
+
+import { FlowNodeInspector } from './FlowNodeInspector';
+
+beforeAll(() => {
+  // Radix Popover / cmdk probe pointer-capture APIs the test DOM lacks.
+  for (const m of ['hasPointerCapture', 'setPointerCapture', 'releasePointerCapture'] as const) {
+    if (!Element.prototype[m]) {
+      // @ts-expect-error test shim
+      Element.prototype[m] = m === 'hasPointerCapture' ? () => false : () => {};
+    }
+  }
+});
+
+afterEach(cleanup);
+
+describe('notify node — add-node palette (real NODE_PALETTE)', () => {
+  it('presents Notify in the Integration group and picks type="notify"', () => {
+    const onPick = vi.fn();
+    render(
+      <NodePalette items={NODE_PALETTE} open onOpenChange={() => {}} onPick={onPick}>
+        <button type="button">Add node</button>
+      </NodePalette>,
+    );
+
+    const notify = screen.getByText('Notify');
+    expect(notify).toBeInTheDocument();
+    fireEvent.click(notify);
+    expect(onPick).toHaveBeenCalledWith('notify');
+  });
+
+  it('maps notify to the Bell icon (distinct from the default CircleDot)', () => {
+    expect(nodeIcon('notify')).toBe(nodeIcon('notify'));
+    expect(nodeIcon('notify')).not.toBe(nodeIcon('some_unknown_type'));
+  });
+});
+
+describe('notify node — inspector renders its config fields', () => {
+  const draft = { nodes: [{ id: 'ping', type: 'notify', label: 'Notify approver', config: {} }] };
+
+  it('shows the notify config editor (recipients / title / message / channels / topic / severity)', () => {
+    render(
+      <FlowNodeInspector
+        type="flow"
+        name="approval_flow"
+        draft={draft}
+        selection={{ kind: 'node', id: 'ping' }}
+        onPatch={vi.fn()}
+        onClearSelection={vi.fn()}
+        readOnly={false}
+        locale="en"
+      />,
+    );
+
+    // The node label input confirms we're on the notify node's inspector.
+    expect(screen.getByDisplayValue('Notify approver')).toBeInTheDocument();
+    // Each authored config field label the built-in descriptor documents.
+    for (const label of ['Recipients', 'Title', 'Message', 'Channels', 'Topic', 'Severity']) {
+      expect(screen.getByText(label)).toBeInTheDocument();
+    }
+  });
+
+  it('writes an edited title back under node.config (matching the runtime)', () => {
+    const onPatch = vi.fn();
+    render(
+      <FlowNodeInspector
+        type="flow"
+        name="approval_flow"
+        draft={draft}
+        selection={{ kind: 'node', id: 'ping' }}
+        onPatch={onPatch}
+        onClearSelection={vi.fn()}
+        readOnly={false}
+        locale="en"
+      />,
+    );
+
+    const titleField = screen.getByPlaceholderText('Your request was approved');
+    fireEvent.change(titleField, { target: { value: 'Approved!' } });
+    const patch = onPatch.mock.calls.at(-1)![0] as { nodes: Array<{ config?: Record<string, unknown> }> };
+    expect(patch.nodes[0].config!.title).toBe('Approved!');
+  });
+});

packages/app-shell/src/views/metadata-admin/previews/flow-canvas-parts.tsx

@@ -10,6 +10,7 @@ import * as React from 'react';
 import {
   AlertCircle,
   AlertTriangle,
+  Bell,
   ChevronRight,
   Code,
   CircleDot,
@@ -85,6 +86,8 @@ export function nodeIcon(type: string): LucideIcon {
     case 'http_request':
     case 'webhook':
       return Globe;
+    case 'notify':
+      return Bell;
     case 'script':
     case 'script_task':
       return Code;
@@ -248,6 +251,7 @@ export function nodeTone(type: string): NodeTone {
       return TONES.record;
     case 'http':
     case 'http_request':
+    case 'notify':
     case 'connector_action':
     case 'script':
     case 'webhook':
@@ -312,6 +316,7 @@ export function nodeCategory(type: string): NodeCategory {
       return 'Human';
     case 'http':
     case 'http_request':
+    case 'notify':
     case 'connector_action':
     case 'script':
     case 'webhook':
@@ -341,6 +346,7 @@ export const NODE_PALETTE: PaletteItem[] = [
   { type: 'approval', label: 'Approval', hint: 'Pause for a human decision', category: 'Human' },
   { type: 'screen', label: 'Screen', hint: 'Collect input from a user', category: 'Human' },
   { type: 'http', label: 'HTTP request', hint: 'Call an external API', category: 'Integration' },
+  { type: 'notify', label: 'Notify', hint: 'Send a notification to users', category: 'Integration' },
   { type: 'connector_action', label: 'Connector', hint: 'Run an integration action', category: 'Integration' },
   { type: 'script', label: 'Script', hint: 'Run custom code', category: 'Integration' },
   { type: 'subflow', label: 'Subflow', hint: 'Invoke another flow', category: 'Flow' },
@@ -385,6 +391,10 @@ export function defaultNodeExtras(type: string): Record<string, unknown> {
       // Seed a node-model approval: at least one approver + spec defaults. The
       // author wires the out-edges with labels `approve` / `reject`.
       return { config: { approvers: [{ type: 'manager' }], behavior: 'first_response', lockRecord: true } };
+    case 'notify':
+      // Seed a sensible notify node: inbox channel + one empty recipient slot,
+      // matching the built-in node's defaults (framework#1895).
+      return { config: { channels: ['inbox'], recipients: [] } };
     case 'http':
     case 'http_request':
       return { config: { method: 'GET' } };

packages/app-shell/src/views/metadata-admin/previews/useFlowNodePalette.test.ts

@@ -9,6 +9,15 @@ describe('mergePalette', () => {
     expect(mergePalette(NODE_PALETTE, [])).toEqual(NODE_PALETTE);
   });
 
+  it('offers `notify` as a first-class Integration palette entry (#1895)', () => {
+    const notify = NODE_PALETTE.find((i) => i.type === 'notify');
+    expect(notify).toBeDefined();
+    expect(notify!.category).toBe('Integration');
+    // Authorable offline (static entry), not only when the engine publishes a
+    // descriptor — mergePalette keeps it when no descriptors are present.
+    expect(mergePalette(NODE_PALETTE, []).some((i) => i.type === 'notify')).toBe(true);
+  });
+
   it('overlays the engine label/description onto a matching base entry, keeping its position', () => {
     const base = [
       { type: 'decision', label: 'Decision', hint: 'Branch on a condition' },