feat(L4): left view switcher + palette-driven drag-and-drop

The two UX gaps the demo exposed:
  1. The left icon strip didn't actually drive the left panel —
     it was just decorative buttons.
  2. There was no way to drag a component from anywhere into the
     canvas.

This change wires both ends of the loop.

* designer/Dragon: add `boost(meta, x, y)` so the palette can
  start a drag of a not-yet-instantiated component. `commit()`
  returns a discriminated union (move | boost) the host can
  `switch` on. New events: startBoost, dropBoost, cancelBoost.
* designer: BuiltinSimulatorHost (new) — wires canvas pointer
  events to the Dragon. Computes a DropTarget from each
  `pointermove` (vertical-thirds algorithm: top → 'before',
  middle → 'inside', bottom → 'after') and commits on
  `pointerup`. Escape cancels. Window-level pointerup so a
  cursor that drifted outside the canvas still commits.
* designer/Project: re-emit the Dragon's boost events on the
  Project emitter so plugins can subscribe in one place.
* editor-skeleton: Skeleton now owns a `leftView` state
  ('outline' | 'components'). The default leftArea renders two
  view-switcher buttons (🌳 / 🧩); the left panel body swaps
  between OutlineView and the new ComponentPalette. The host
  can drive the state via `leftView` + `onLeftViewChange`
  (controlled mode).
* editor-skeleton: ComponentPalette (new) — a vertical list of
  registered components, each row is a `pointerdown` source for
  `dragon.boost`. Pressed-row visual feedback via
  startBoost/dropBoost/cancelBoost subscriptions.
* editor-skeleton: Skeleton mounts BuiltinSimulatorHost on the
  canvas element as soon as React attaches it (effect deps
  canvasEl + project).
* designer: `DocumentModel.rename` now refuses to rename the
  document root (parent === null). The root's componentName is
  the render entry — renaming it would leave the simulator
  with an unresolvable name. Settings panel also hides the
  Rename button and shows an italic "root" hint when the root
  is the selected node. Both layers guard; the API guard is
  the safety net, the UI guard is the friendly face.
* demo: extended leftArea with 🌳/🧩 view switcher buttons,
  wired leftView/onLeftViewChange to <Skeleton> in controlled
  mode. The user can now flip to the palette, drag a Button
  onto the canvas, and watch it insert + auto-select.

Author: lir-navcoo

examples/demo/src/main.ts

@@ -140,6 +140,13 @@ function App({ engine }: { engine: ISapuEngine }) {
   // `Input` setter for that prop.
   const [customOn, setCustomOn] = useState(false);
 
+  // L4 left view: which built-in view the left panel is showing.
+  // The demo drives the Skeleton in CONTROLLED mode (passes
+  // `leftView` + `onLeftViewChange`) so the icon strip in the
+  // leftArea slot can flip the state. Without this, the user has
+  // no way to switch between Outline and Component palette.
+  const [leftView, setLeftView] = useState<'outline' | 'components'>('outline');
+
   // Push schema into the project AFTER render, never during it.
   useEffect(() => {
     project.load(schema);
@@ -394,12 +401,39 @@ function App({ engine }: { engine: ISapuEngine }) {
 
   // The Skeleton's `leftArea` slot — a thin icon strip to the LEFT
   // of the outline panel. Ali's `leftArea` is the icon column.
-  // For the demo we just put a couple of icon buttons; their
-  // semantics are TBD but the slot itself is the proof.
+  // The demo uses CONTROLLED mode (`leftView` + `onLeftViewChange`
+  // wired to <Skeleton>) so the user can flip between the Outline
+  // tree and the Component palette (drag-and-drop source). The
+  // ⧉ and ↻ buttons are demo-only (open second doc / reset).
   const leftArea = () =>
     React.createElement(
       'div',
       { className: 'flex flex-col items-center gap-1' },
+      React.createElement(
+        'button',
+        {
+          className:
+            'w-7 h-7 flex items-center justify-center border border-slate-200 ' +
+            'rounded hover:bg-slate-100 text-sm ' +
+            (leftView === 'outline' ? 'bg-blue-100 text-blue-700 ring-1 ring-blue-300' : ''),
+          onClick: () => setLeftView('outline'),
+          title: 'Outline view',
+        },
+        '🌳',
+      ),
+      React.createElement(
+        'button',
+        {
+          className:
+            'w-7 h-7 flex items-center justify-center border border-slate-200 ' +
+            'rounded hover:bg-slate-100 text-sm ' +
+            (leftView === 'components' ? 'bg-blue-100 text-blue-700 ring-1 ring-blue-300' : ''),
+          onClick: () => setLeftView('components'),
+          title: 'Component palette (drag to canvas)',
+        },
+        '🧩',
+      ),
+      React.createElement('div', { className: 'w-5 h-px bg-slate-200 my-0.5' }),
       React.createElement(
         'button',
         {
@@ -450,6 +484,8 @@ function App({ engine }: { engine: ISapuEngine }) {
           setterConfig,
           topArea,
           leftArea,
+          leftView,
+          onLeftViewChange: setLeftView,
         }),
       ),
     ),

packages/designer/src/document.ts

@@ -119,6 +119,14 @@ export class DocumentModel implements IDocumentModel {
   }
 
   rename(node: Node, newName: string): void {
+    // The root componentName is the render entry (e.g. "Page" maps
+    // to the host's <Page> component). Renaming it would change
+    // the document's *root type* — the simulator would no longer
+    // have a matching component in the registry and would fall
+    // back to a placeholder. Refuse the mutation here so the
+    // safety net is in place even if a host forgets to hide the
+    // Rename UI for the root selection.
+    if (node.parent === null) return;
     const old = node.schema.componentName;
     if (old === newName) return;
     node.schema.componentName = newName;

packages/designer/src/dragon.ts

@@ -2,23 +2,27 @@
  * @monbolc/lowcode-designer — Dragon
  *
  * Drag state machine. Tracks:
- *   - which node is being dragged
+ *   - which existing node is being dragged (move), OR
+ *   - which component meta is being dragged from a palette (boost)
  *   - current pointer position
  *   - current drop target (parent node + insertion index)
  *
  * The host wires pointer events on the canvas and calls
- * `dragon.move(x, y)` and `dragon.drop()` as appropriate.
+ * `dragon.move(x, y)` and `dragon.commit()` as appropriate.
  *
  * For the L3 milestone this is a self-contained state machine.
  * Visual feedback (ghost, insertion indicator) is rendered by the
  * Skeleton layer (L4+).
  */
 
 import { Emitter } from '@monbolc/lowcode-utils';
+import type { JSONValue } from '@monbolc/lowcode-types';
 
 export interface DragonState {
   /** id of the node being dragged, or null. */
   draggingNodeId: string | null;
+  /** Boost payload (the component about to be instantiated on drop), or null. */
+  boost: BoostMeta | null;
   /** Current pointer x in viewport coords. */
   x: number;
   /** Current pointer y in viewport coords. */
@@ -36,62 +40,114 @@ export interface DropTarget {
   placement: 'before' | 'after' | 'inside';
 }
 
+/**
+ * Payload for a "boost" — a drag that hasn't started from an existing
+ * node. The component is created from `componentName` (+ optional
+ * `initialProps`) on a successful drop.
+ */
+export interface BoostMeta {
+  componentName: string;
+  initialProps?: Record<string, JSONValue>;
+}
+
 export interface DragonEvents extends Record<string, unknown> {
-  /** A drag just started. */
+  /** A drag of an existing node just started. */
   start: { nodeId: string };
+  /** A boost (palette → canvas) drag just started. */
+  startBoost: { meta: BoostMeta };
   /** Pointer moved during a drag. */
   move: { x: number; y: number; dropTarget: DropTarget | null };
   /** A drag ended without a successful drop. */
   cancel: { nodeId: string };
-  /** A drag ended with a successful drop. */
+  /** A boost drag ended without a successful drop. */
+  cancelBoost: { meta: BoostMeta };
+  /** A drag of an existing node ended with a successful drop. */
   drop: { nodeId: string; target: DropTarget };
+  /** A boost drag ended with a successful drop. */
+  dropBoost: { meta: BoostMeta; target: DropTarget };
 }
 
 export class Dragon {
   readonly events = new Emitter<DragonEvents>();
-  private _state: DragonState = { draggingNodeId: null, x: 0, y: 0, dropTarget: null };
+  private _state: DragonState = { draggingNodeId: null, boost: null, x: 0, y: 0, dropTarget: null };
 
   get state(): DragonState {
     return this._state;
   }
 
   get isDragging(): boolean {
-    return this._state.draggingNodeId !== null;
+    return this._state.draggingNodeId !== null || this._state.boost !== null;
+  }
+
+  /** True iff a boost (palette → canvas) drag is in progress. */
+  get isBoosting(): boolean {
+    return this._state.boost !== null;
   }
 
   start(nodeId: string, x: number, y: number): void {
-    if (this._state.draggingNodeId) return;
-    this._state = { draggingNodeId: nodeId, x, y, dropTarget: null };
+    if (this._state.draggingNodeId || this._state.boost) return;
+    this._state = { draggingNodeId: nodeId, boost: null, x, y, dropTarget: null };
     this.events.emit('start', { nodeId });
   }
 
+  /**
+   * Start a "boost" drag — the user is dragging a not-yet-instantiated
+   * component out of a palette. On a successful `commit()`, the host
+   * should create a new schema node from `meta.componentName` at the
+   * drop target.
+   */
+  boost(meta: BoostMeta, x: number, y: number): void {
+    if (this._state.draggingNodeId || this._state.boost) return;
+    this._state = { draggingNodeId: null, boost: meta, x, y, dropTarget: null };
+    this.events.emit('startBoost', { meta });
+  }
+
   move(x: number, y: number, dropTarget: DropTarget | null = null): void {
-    if (!this._state.draggingNodeId) return;
+    if (!this._state.draggingNodeId && !this._state.boost) return;
     this._state = { ...this._state, x, y, dropTarget };
     this.events.emit('move', { x, y, dropTarget });
   }
 
-  /** Mark the drag as successful; emits a `drop` event with the
-   * current drop target. The host should commit the actual mutation
-   * (e.g. via Project.document.move) on receipt. */
-  commit(): { nodeId: string; target: DropTarget } | null {
-    const id = this._state.draggingNodeId;
-    const target = this._state.dropTarget;
-    if (!id) return null;
-    this._state = { draggingNodeId: null, x: 0, y: 0, dropTarget: null };
-    if (target) {
-      this.events.emit('drop', { nodeId: id, target });
+  /**
+   * Mark the drag as successful; emits a `drop` (existing-node move)
+   * or `dropBoost` (palette → canvas) event with the current target.
+   * The host should commit the actual mutation on receipt.
+   *
+   * Returns a discriminated union so the caller can dispatch on
+   * `'nodeId' in result` vs `'meta' in result`.
+   */
+  commit():
+    | { kind: 'move'; nodeId: string; target: DropTarget }
+    | { kind: 'boost'; meta: BoostMeta; target: DropTarget }
+    | null {
+    const { draggingNodeId, boost, dropTarget } = this._state;
+    if (!draggingNodeId && !boost) return null;
+    this._state = { draggingNodeId: null, boost: null, x: 0, y: 0, dropTarget: null };
+    if (dropTarget) {
+      if (boost) {
+        this.events.emit('dropBoost', { meta: boost, target: dropTarget });
+        return { kind: 'boost', meta: boost, target: dropTarget };
+      }
+      this.events.emit('drop', { nodeId: draggingNodeId!, target: dropTarget });
+      return { kind: 'move', nodeId: draggingNodeId!, target: dropTarget };
+    }
+    if (boost) {
+      this.events.emit('cancelBoost', { meta: boost });
     } else {
-      this.events.emit('cancel', { nodeId: id });
+      this.events.emit('cancel', { nodeId: draggingNodeId! });
     }
-    return target ? { nodeId: id, target } : null;
+    return null;
   }
 
   /** Cancel an in-progress drag (e.g. on Escape). */
   cancel(): void {
-    const id = this._state.draggingNodeId;
-    if (!id) return;
-    this._state = { draggingNodeId: null, x: 0, y: 0, dropTarget: null };
-    this.events.emit('cancel', { nodeId: id });
+    const { draggingNodeId, boost } = this._state;
+    if (!draggingNodeId && !boost) return;
+    this._state = { draggingNodeId: null, boost: null, x: 0, y: 0, dropTarget: null };
+    if (boost) {
+      this.events.emit('cancelBoost', { meta: boost });
+    } else {
+      this.events.emit('cancel', { nodeId: draggingNodeId! });
+    }
   }
 }

packages/designer/src/index.ts

@@ -20,11 +20,14 @@ export { Project } from './project';
 export type { ProjectEvents } from './project';
 
 export { Dragon } from './dragon';
-export type { DragonEvents, DragonState, DropTarget } from './dragon';
+export type { DragonEvents, DragonState, DropTarget, BoostMeta } from './dragon';
 
 export { Simulator } from './simulator';
 export type { SimulatorOptions } from './simulator';
 
+export { BuiltinSimulatorHost } from './simulator-host';
+export type { SimulatorHostOptions } from './simulator-host';
+
 export {
   InsertCommand,
   RemoveCommand,

packages/designer/src/project.ts

@@ -51,8 +51,11 @@ export class Project {
     this.document.events.on('nodeMoved', (e) => this.events.emit('nodeMoved', e));
     this.document.events.on('nodeRenamed', (e) => this.events.emit('nodeRenamed', e));
     this.dragon.events.on('start', (e) => this.events.emit('start', e));
+    this.dragon.events.on('startBoost', (e) => this.events.emit('startBoost', e));
     this.dragon.events.on('move', (e) => this.events.emit('move', e));
     this.dragon.events.on('end', (e) => this.events.emit('end', e));
+    this.dragon.events.on('dropBoost', (e) => this.events.emit('dropBoost', e));
+    this.dragon.events.on('cancelBoost', (e) => this.events.emit('cancelBoost', e));
   }
 
   /** Replace the document with a new root schema. */