@railway/inkwell 1.0.0 → 1.1.1

package/README.md

@@ -51,26 +51,18 @@ pnpm dev
 
 ## Releases
 
-Versioning and `CHANGELOG.md` are managed by [Changesets](https://github.com/changesets/changesets). Publishing to npm runs via GitHub Actions on a `v*` tag push.
+Releases are automated. Every PR carries exactly one label that determines the next version bump:
 
-When you open a PR that should show up in the changelog:
+| Label | Effect |
+|---|---|
+| `release/patch` | Bumps the patch version (e.g. `1.1.0` → `1.1.1`) |
+| `release/minor` | Bumps the minor version (e.g. `1.1.0` → `1.2.0`) |
+| `release/major` | Bumps the major version (e.g. `1.1.0` → `2.0.0`) |
+| `release/skip`  | No version bump (use for docs-only or chore PRs) |
 
-```bash
-pnpm changeset   # pick bump type, write a user-facing summary
-```
-
-Commit the generated `.changeset/*.md` file alongside your code.
-
-To cut a release from `main`:
-
-```bash
-pnpm changeset version   # bumps packages/inkwell/package.json + writes CHANGELOG.md
-git commit -am "🚀 release: v$(node -p "require('./packages/inkwell/package.json').version")"
-git tag "v$(node -p "require('./packages/inkwell/package.json').version")"
-git push --follow-tags
-```
+When a labeled PR merges to `main`, the `auto-release` workflow batches with any other recently-merged PRs, picks the highest bump across them, tags `vX.Y.Z`, and pushes. The tag push triggers the `publish` workflow, which generates release notes from PR titles since the previous tag, drafts a GitHub Release, publishes to npm, and un-drafts.
 
-Pushing the `v*` tag triggers the publish workflow.
+Release notes live on the [GitHub Releases page](https://github.com/railwayapp/inkwell/releases). There is no in-repo `CHANGELOG.md`.
 
 ## License
 

package/dist/index.cjs

@@ -148,7 +148,7 @@ function BubbleMenuWidget({
         left: position.left,
         transform: position.placement === "above" ? "translateX(-50%) translateY(-100%)" : "translateX(-50%)",
         marginTop: position.placement === "above" ? -8 : 8,
-        zIndex: 1100
+        zIndex: 9999
       },
       onMouseDown: (e) => e.preventDefault(),
       children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: cls("inner"), children: items.map((item) => /* @__PURE__ */ jsxRuntime.jsx(item.render, { wrapSelection }, item.key)) })
@@ -1436,7 +1436,8 @@ var InkwellEditorClient = react.forwardRef(
     activePluginRef.current = activePlugin;
     const pluginPositionRef = react.useRef({
       top: 0,
-      left: 0
+      left: 0,
+      cursorRect: { top: 0, bottom: 0, left: 0 }
     });
     const forwardedKeyListenersRef = react.useRef(/* @__PURE__ */ new Map());
     const wrapperRef = react.useRef(null);
@@ -1547,10 +1548,14 @@ var InkwellEditorClient = react.forwardRef(
       ]
     );
     const getCursorPosition = react.useCallback(() => {
+      const empty = {
+        top: 0,
+        left: 0,
+        cursorRect: { top: 0, bottom: 0, left: 0 }
+      };
       try {
         const domSelection = window.getSelection();
-        if (!domSelection || domSelection.rangeCount === 0)
-          return { top: 0, left: 0 };
+        if (!domSelection || domSelection.rangeCount === 0) return empty;
         const range = domSelection.getRangeAt(0);
         let rect = range.getBoundingClientRect();
         if (rect.width === 0 && rect.height === 0 && domSelection.anchorNode) {
@@ -1558,14 +1563,22 @@ var InkwellEditorClient = react.forwardRef(
           if (node) rect = node.getBoundingClientRect();
         }
         const wrapperEl = wrapperRef.current;
-        if (!wrapperEl) return { top: 0, left: 0 };
+        if (!wrapperEl) return empty;
         const wrapperRect = wrapperEl.getBoundingClientRect();
+        const cursorTop = rect.top - wrapperRect.top;
+        const cursorBottom = rect.bottom - wrapperRect.top;
+        const cursorLeft = rect.left - wrapperRect.left;
         return {
-          top: rect.bottom - wrapperRect.top + 4,
-          left: rect.left - wrapperRect.left
+          top: cursorBottom + 4,
+          left: cursorLeft,
+          cursorRect: {
+            top: cursorTop,
+            bottom: cursorBottom,
+            left: cursorLeft
+          }
         };
       } catch {
-        return { top: 0, left: 0 };
+        return empty;
       }
     }, []);
     const wrapSelection = react.useCallback(
@@ -1833,7 +1846,11 @@ var InkwellEditorClient = react.forwardRef(
       query: activePlugin === plugin ? activePluginQuery : "",
       onSelect: handlePluginSelect,
       onDismiss: dismissPlugin,
-      position: pluginPositionRef.current,
+      position: {
+        top: pluginPositionRef.current.top,
+        left: pluginPositionRef.current.left
+      },
+      cursorRect: pluginPositionRef.current.cursorRect,
       editorRef: editorElRef,
       editor: pluginEditor,
       wrapSelection,
@@ -2273,8 +2290,10 @@ function createCompletionsPlugin({
 var BASE = "inkwell-plugin-picker";
 var pluginPickerClass = {
   popup: `${BASE}-popup`,
+  popupFlipped: `${BASE}-popup-flipped`,
   picker: `${BASE}`,
   search: `${BASE}-search`,
+  list: `${BASE}-list`,
   item: `${BASE}-item`,
   itemActive: `${BASE}-item-active`,
   empty: `${BASE}-empty`,
@@ -2282,6 +2301,74 @@ var pluginPickerClass = {
   subtitle: `${BASE}-subtitle`,
   preview: `${BASE}-preview`
 };
+var POPUP_GAP = 4;
+var VIEWPORT_MARGIN = 8;
+var CURSOR_HEIGHT_FALLBACK = 20;
+function usePickerPlacement(position, cursorRect) {
+  const [popupEl, setPopupEl] = react.useState(null);
+  const [placement, setPlacement] = react.useState({ flippedAbove: false, leftOverride: null });
+  const cursorTopWrapper = cursorRect?.top ?? Math.max(0, position.top - POPUP_GAP - CURSOR_HEIGHT_FALLBACK);
+  const cursorBottomWrapper = cursorRect?.bottom ?? Math.max(0, position.top - POPUP_GAP);
+  const cursorLeftWrapper = cursorRect?.left ?? position.left;
+  react.useLayoutEffect(() => {
+    if (!popupEl) return;
+    const measure = () => {
+      const offsetParent = popupEl.offsetParent;
+      if (!(offsetParent instanceof HTMLElement)) return;
+      const wrapperRect = offsetParent.getBoundingClientRect();
+      const popupRect = popupEl.getBoundingClientRect();
+      const popupHeight = popupRect.height;
+      const popupWidth = popupRect.width;
+      const cursorTopViewport = wrapperRect.top + cursorTopWrapper;
+      const cursorBottomViewport = wrapperRect.top + cursorBottomWrapper;
+      const cursorLeftViewport = wrapperRect.left + cursorLeftWrapper;
+      const spaceBelowViewport = window.innerHeight - cursorBottomViewport - VIEWPORT_MARGIN;
+      const spaceBelowWrapper = wrapperRect.bottom - cursorBottomViewport;
+      const spaceBelow = Math.min(spaceBelowViewport, spaceBelowWrapper);
+      const spaceAbove = cursorTopViewport - VIEWPORT_MARGIN;
+      const needsFlip = popupHeight + POPUP_GAP > spaceBelow;
+      const fitsAbove = popupHeight + POPUP_GAP <= spaceAbove;
+      const flippedAbove = needsFlip && fitsAbove;
+      const maxRightViewport = window.innerWidth - VIEWPORT_MARGIN;
+      const popupRightIfDefault = cursorLeftViewport + popupWidth;
+      const leftOverride = popupRightIfDefault > maxRightViewport ? Math.max(
+        VIEWPORT_MARGIN - wrapperRect.left,
+        maxRightViewport - popupWidth - wrapperRect.left
+      ) : null;
+      setPlacement(
+        (prev) => prev.flippedAbove === flippedAbove && prev.leftOverride === leftOverride ? prev : { flippedAbove, leftOverride }
+      );
+    };
+    measure();
+    const ResizeObserverCtor = typeof window !== "undefined" ? window.ResizeObserver : void 0;
+    const resizeObserver = ResizeObserverCtor ? new ResizeObserverCtor(() => measure()) : null;
+    resizeObserver?.observe(popupEl);
+    window.addEventListener("resize", measure);
+    window.addEventListener("scroll", measure, true);
+    return () => {
+      resizeObserver?.disconnect();
+      window.removeEventListener("resize", measure);
+      window.removeEventListener("scroll", measure, true);
+    };
+  }, [popupEl, cursorTopWrapper, cursorBottomWrapper, cursorLeftWrapper]);
+  const style = {
+    position: "absolute",
+    top: placement.flippedAbove ? cursorTopWrapper - POPUP_GAP : position.top,
+    left: placement.leftOverride ?? position.left,
+    transform: placement.flippedAbove ? "translateY(-100%)" : void 0,
+    zIndex: 1001
+  };
+  const className = placement.flippedAbove ? `${pluginPickerClass.popup} ${pluginPickerClass.popupFlipped}` : pluginPickerClass.popup;
+  return {
+    setPopupEl,
+    style,
+    className,
+    flippedAbove: placement.flippedAbove
+  };
+}
+function usePluginPopupPlacement(position, cursorRect) {
+  return usePickerPlacement(position, cursorRect);
+}
 function PluginMenuPrimitive({
   items,
   search,
@@ -2293,6 +2380,7 @@ function PluginMenuPrimitive({
   onSelect,
   onDismiss,
   position,
+  cursorRect,
   subscribeForwardedKey
 }) {
   const [selectedIndex, setSelectedIndex] = react.useState(0);
@@ -2437,16 +2525,13 @@ function PluginMenuPrimitive({
       updateSelectedIndex
     ]
   );
+  const placement = usePickerPlacement(position, cursorRect);
   return /* @__PURE__ */ jsxRuntime.jsx(
     "div",
     {
-      className: pluginPickerClass.popup,
-      style: {
-        position: "absolute",
-        top: position.top,
-        left: position.left,
-        zIndex: 1001
-      },
+      ref: placement.setPopupEl,
+      className: placement.className,
+      style: placement.style,
       onMouseDown: (event) => event.preventDefault(),
       children: /* @__PURE__ */ jsxRuntime.jsxs(
         "div",
@@ -2460,7 +2545,7 @@ function PluginMenuPrimitive({
           "aria-activedescendant": results.length > 0 ? activeOptionId : void 0,
           children: [
             /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.search, "aria-label": placeholder, children: query || placeholder }),
-            results.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.empty, role: "status", children: emptyMessage }) : /* @__PURE__ */ jsxRuntime.jsx("div", { id: listboxId, role: "listbox", children: renderedResults })
+            results.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.empty, role: "status", children: emptyMessage }) : /* @__PURE__ */ jsxRuntime.jsx("div", { id: listboxId, role: "listbox", className: pluginPickerClass.list, children: renderedResults })
           ]
         }
       )
@@ -2622,6 +2707,7 @@ var SlashCommandMenuInner = react.forwardRef(function SlashCommandMenuInner2({
   onExecute,
   onDismiss,
   position,
+  cursorRect,
   getEditor
 }, ref) {
   const [mode, setMode] = react.useState("commands");
@@ -2785,17 +2871,14 @@ var SlashCommandMenuInner = react.forwardRef(function SlashCommandMenuInner2({
       selectedIndex
     ]
   );
+  const placement = usePluginPopupPlacement(position, cursorRect);
   if (mode === "ready" && selectedCommand) {
     return /* @__PURE__ */ jsxRuntime.jsx(
       "div",
       {
-        className: pluginPickerClass.popup,
-        style: {
-          position: "absolute",
-          top: position.top,
-          left: position.left,
-          zIndex: 1001
-        },
+        ref: placement.setPopupEl,
+        className: placement.className,
+        style: placement.style,
         children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.picker, children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: "inkwell-plugin-slash-commands-execute", children: "Enter to execute \xB7 Esc to cancel" }) })
       }
     );
@@ -2803,13 +2886,9 @@ var SlashCommandMenuInner = react.forwardRef(function SlashCommandMenuInner2({
   return /* @__PURE__ */ jsxRuntime.jsx(
     "div",
     {
-      className: pluginPickerClass.popup,
-      style: {
-        position: "absolute",
-        top: position.top,
-        left: position.left,
-        zIndex: 1001
-      },
+      ref: placement.setPopupEl,
+      className: placement.className,
+      style: placement.style,
       children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: pluginPickerClass.picker, children: [
         /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.search, children: mode === "commands" ? `/${query}` : `${selectedCommand ? `/${selectedCommand.name} ` : ""}${query}` }),
         loadingArgs && items.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.empty, children: "Loading..." }) : items.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.empty, children: emptyMessage }) : /* @__PURE__ */ jsxRuntime.jsx(
@@ -2818,6 +2897,7 @@ var SlashCommandMenuInner = react.forwardRef(function SlashCommandMenuInner2({
             id: listboxId,
             role: "listbox",
             "aria-activedescendant": activeOptionId,
+            className: pluginPickerClass.list,
             children: items.map((item, index) => {
               const active = index === selectedIndex;
               return /* @__PURE__ */ jsxRuntime.jsxs(

package/dist/index.d.cts

@@ -180,11 +180,20 @@ interface PluginRenderProps {
     onSelect: (content: string) => void;
     /** Deactivate this plugin. */
     onDismiss: () => void;
-    /** Cursor position when the trigger fired. */
+    /** Cursor position when the trigger fired. Wrapper-relative; sits just
+     *  below the caret so a popup with `top: position.top` renders below it. */
     position: {
         top: number;
         left: number;
     };
+    /** Wrapper-relative caret bounding rect when the trigger fired. Lets pickers
+     *  flip above the caret when there isn't room below. Optional for backwards
+     *  compatibility with consumers that pass synthesized props. */
+    cursorRect?: {
+        top: number;
+        bottom: number;
+        left: number;
+    };
     /** Ref to the editable DOM element. */
     editorRef: RefObject<HTMLDivElement | null>;
     /** Narrow editor controller for plugin actions. */

package/dist/index.d.ts

@@ -180,11 +180,20 @@ interface PluginRenderProps {
     onSelect: (content: string) => void;
     /** Deactivate this plugin. */
     onDismiss: () => void;
-    /** Cursor position when the trigger fired. */
+    /** Cursor position when the trigger fired. Wrapper-relative; sits just
+     *  below the caret so a popup with `top: position.top` renders below it. */
     position: {
         top: number;
         left: number;
     };
+    /** Wrapper-relative caret bounding rect when the trigger fired. Lets pickers
+     *  flip above the caret when there isn't room below. Optional for backwards
+     *  compatibility with consumers that pass synthesized props. */
+    cursorRect?: {
+        top: number;
+        bottom: number;
+        left: number;
+    };
     /** Ref to the editable DOM element. */
     editorRef: RefObject<HTMLDivElement | null>;
     /** Narrow editor controller for plugin actions. */

package/dist/index.js

@@ -133,7 +133,7 @@ function BubbleMenuWidget({
         left: position.left,
         transform: position.placement === "above" ? "translateX(-50%) translateY(-100%)" : "translateX(-50%)",
         marginTop: position.placement === "above" ? -8 : 8,
-        zIndex: 1100
+        zIndex: 9999
       },
       onMouseDown: (e) => e.preventDefault(),
       children: /* @__PURE__ */ jsx("div", { className: cls("inner"), children: items.map((item) => /* @__PURE__ */ jsx(item.render, { wrapSelection }, item.key)) })
@@ -1421,7 +1421,8 @@ var InkwellEditorClient = forwardRef(
     activePluginRef.current = activePlugin;
     const pluginPositionRef = useRef({
       top: 0,
-      left: 0
+      left: 0,
+      cursorRect: { top: 0, bottom: 0, left: 0 }
     });
     const forwardedKeyListenersRef = useRef(/* @__PURE__ */ new Map());
     const wrapperRef = useRef(null);
@@ -1532,10 +1533,14 @@ var InkwellEditorClient = forwardRef(
       ]
     );
     const getCursorPosition = useCallback(() => {
+      const empty = {
+        top: 0,
+        left: 0,
+        cursorRect: { top: 0, bottom: 0, left: 0 }
+      };
       try {
         const domSelection = window.getSelection();
-        if (!domSelection || domSelection.rangeCount === 0)
-          return { top: 0, left: 0 };
+        if (!domSelection || domSelection.rangeCount === 0) return empty;
         const range = domSelection.getRangeAt(0);
         let rect = range.getBoundingClientRect();
         if (rect.width === 0 && rect.height === 0 && domSelection.anchorNode) {
@@ -1543,14 +1548,22 @@ var InkwellEditorClient = forwardRef(
           if (node) rect = node.getBoundingClientRect();
         }
         const wrapperEl = wrapperRef.current;
-        if (!wrapperEl) return { top: 0, left: 0 };
+        if (!wrapperEl) return empty;
         const wrapperRect = wrapperEl.getBoundingClientRect();
+        const cursorTop = rect.top - wrapperRect.top;
+        const cursorBottom = rect.bottom - wrapperRect.top;
+        const cursorLeft = rect.left - wrapperRect.left;
         return {
-          top: rect.bottom - wrapperRect.top + 4,
-          left: rect.left - wrapperRect.left
+          top: cursorBottom + 4,
+          left: cursorLeft,
+          cursorRect: {
+            top: cursorTop,
+            bottom: cursorBottom,
+            left: cursorLeft
+          }
         };
       } catch {
-        return { top: 0, left: 0 };
+        return empty;
       }
     }, []);
     const wrapSelection = useCallback(
@@ -1818,7 +1831,11 @@ var InkwellEditorClient = forwardRef(
       query: activePlugin === plugin ? activePluginQuery : "",
       onSelect: handlePluginSelect,
       onDismiss: dismissPlugin,
-      position: pluginPositionRef.current,
+      position: {
+        top: pluginPositionRef.current.top,
+        left: pluginPositionRef.current.left
+      },
+      cursorRect: pluginPositionRef.current.cursorRect,
       editorRef: editorElRef,
       editor: pluginEditor,
       wrapSelection,
@@ -2258,8 +2275,10 @@ function createCompletionsPlugin({
 var BASE = "inkwell-plugin-picker";
 var pluginPickerClass = {
   popup: `${BASE}-popup`,
+  popupFlipped: `${BASE}-popup-flipped`,
   picker: `${BASE}`,
   search: `${BASE}-search`,
+  list: `${BASE}-list`,
   item: `${BASE}-item`,
   itemActive: `${BASE}-item-active`,
   empty: `${BASE}-empty`,
@@ -2267,6 +2286,74 @@ var pluginPickerClass = {
   subtitle: `${BASE}-subtitle`,
   preview: `${BASE}-preview`
 };
+var POPUP_GAP = 4;
+var VIEWPORT_MARGIN = 8;
+var CURSOR_HEIGHT_FALLBACK = 20;
+function usePickerPlacement(position, cursorRect) {
+  const [popupEl, setPopupEl] = useState(null);
+  const [placement, setPlacement] = useState({ flippedAbove: false, leftOverride: null });
+  const cursorTopWrapper = cursorRect?.top ?? Math.max(0, position.top - POPUP_GAP - CURSOR_HEIGHT_FALLBACK);
+  const cursorBottomWrapper = cursorRect?.bottom ?? Math.max(0, position.top - POPUP_GAP);
+  const cursorLeftWrapper = cursorRect?.left ?? position.left;
+  useLayoutEffect(() => {
+    if (!popupEl) return;
+    const measure = () => {
+      const offsetParent = popupEl.offsetParent;
+      if (!(offsetParent instanceof HTMLElement)) return;
+      const wrapperRect = offsetParent.getBoundingClientRect();
+      const popupRect = popupEl.getBoundingClientRect();
+      const popupHeight = popupRect.height;
+      const popupWidth = popupRect.width;
+      const cursorTopViewport = wrapperRect.top + cursorTopWrapper;
+      const cursorBottomViewport = wrapperRect.top + cursorBottomWrapper;
+      const cursorLeftViewport = wrapperRect.left + cursorLeftWrapper;
+      const spaceBelowViewport = window.innerHeight - cursorBottomViewport - VIEWPORT_MARGIN;
+      const spaceBelowWrapper = wrapperRect.bottom - cursorBottomViewport;
+      const spaceBelow = Math.min(spaceBelowViewport, spaceBelowWrapper);
+      const spaceAbove = cursorTopViewport - VIEWPORT_MARGIN;
+      const needsFlip = popupHeight + POPUP_GAP > spaceBelow;
+      const fitsAbove = popupHeight + POPUP_GAP <= spaceAbove;
+      const flippedAbove = needsFlip && fitsAbove;
+      const maxRightViewport = window.innerWidth - VIEWPORT_MARGIN;
+      const popupRightIfDefault = cursorLeftViewport + popupWidth;
+      const leftOverride = popupRightIfDefault > maxRightViewport ? Math.max(
+        VIEWPORT_MARGIN - wrapperRect.left,
+        maxRightViewport - popupWidth - wrapperRect.left
+      ) : null;
+      setPlacement(
+        (prev) => prev.flippedAbove === flippedAbove && prev.leftOverride === leftOverride ? prev : { flippedAbove, leftOverride }
+      );
+    };
+    measure();
+    const ResizeObserverCtor = typeof window !== "undefined" ? window.ResizeObserver : void 0;
+    const resizeObserver = ResizeObserverCtor ? new ResizeObserverCtor(() => measure()) : null;
+    resizeObserver?.observe(popupEl);
+    window.addEventListener("resize", measure);
+    window.addEventListener("scroll", measure, true);
+    return () => {
+      resizeObserver?.disconnect();
+      window.removeEventListener("resize", measure);
+      window.removeEventListener("scroll", measure, true);
+    };
+  }, [popupEl, cursorTopWrapper, cursorBottomWrapper, cursorLeftWrapper]);
+  const style = {
+    position: "absolute",
+    top: placement.flippedAbove ? cursorTopWrapper - POPUP_GAP : position.top,
+    left: placement.leftOverride ?? position.left,
+    transform: placement.flippedAbove ? "translateY(-100%)" : void 0,
+    zIndex: 1001
+  };
+  const className = placement.flippedAbove ? `${pluginPickerClass.popup} ${pluginPickerClass.popupFlipped}` : pluginPickerClass.popup;
+  return {
+    setPopupEl,
+    style,
+    className,
+    flippedAbove: placement.flippedAbove
+  };
+}
+function usePluginPopupPlacement(position, cursorRect) {
+  return usePickerPlacement(position, cursorRect);
+}
 function PluginMenuPrimitive({
   items,
   search,
@@ -2278,6 +2365,7 @@ function PluginMenuPrimitive({
   onSelect,
   onDismiss,
   position,
+  cursorRect,
   subscribeForwardedKey
 }) {
   const [selectedIndex, setSelectedIndex] = useState(0);
@@ -2422,16 +2510,13 @@ function PluginMenuPrimitive({
       updateSelectedIndex
     ]
   );
+  const placement = usePickerPlacement(position, cursorRect);
   return /* @__PURE__ */ jsx(
     "div",
     {
-      className: pluginPickerClass.popup,
-      style: {
-        position: "absolute",
-        top: position.top,
-        left: position.left,
-        zIndex: 1001
-      },
+      ref: placement.setPopupEl,
+      className: placement.className,
+      style: placement.style,
       onMouseDown: (event) => event.preventDefault(),
       children: /* @__PURE__ */ jsxs(
         "div",
@@ -2445,7 +2530,7 @@ function PluginMenuPrimitive({
           "aria-activedescendant": results.length > 0 ? activeOptionId : void 0,
           children: [
             /* @__PURE__ */ jsx("div", { className: pluginPickerClass.search, "aria-label": placeholder, children: query || placeholder }),
-            results.length === 0 ? /* @__PURE__ */ jsx("div", { className: pluginPickerClass.empty, role: "status", children: emptyMessage }) : /* @__PURE__ */ jsx("div", { id: listboxId, role: "listbox", children: renderedResults })
+            results.length === 0 ? /* @__PURE__ */ jsx("div", { className: pluginPickerClass.empty, role: "status", children: emptyMessage }) : /* @__PURE__ */ jsx("div", { id: listboxId, role: "listbox", className: pluginPickerClass.list, children: renderedResults })
           ]
         }
       )
@@ -2607,6 +2692,7 @@ var SlashCommandMenuInner = forwardRef(function SlashCommandMenuInner2({
   onExecute,
   onDismiss,
   position,
+  cursorRect,
   getEditor
 }, ref) {
   const [mode, setMode] = useState("commands");
@@ -2770,17 +2856,14 @@ var SlashCommandMenuInner = forwardRef(function SlashCommandMenuInner2({
       selectedIndex
     ]
   );
+  const placement = usePluginPopupPlacement(position, cursorRect);
   if (mode === "ready" && selectedCommand) {
     return /* @__PURE__ */ jsx(
       "div",
       {
-        className: pluginPickerClass.popup,
-        style: {
-          position: "absolute",
-          top: position.top,
-          left: position.left,
-          zIndex: 1001
-        },
+        ref: placement.setPopupEl,
+        className: placement.className,
+        style: placement.style,
         children: /* @__PURE__ */ jsx("div", { className: pluginPickerClass.picker, children: /* @__PURE__ */ jsx("div", { className: "inkwell-plugin-slash-commands-execute", children: "Enter to execute \xB7 Esc to cancel" }) })
       }
     );
@@ -2788,13 +2871,9 @@ var SlashCommandMenuInner = forwardRef(function SlashCommandMenuInner2({
   return /* @__PURE__ */ jsx(
     "div",
     {
-      className: pluginPickerClass.popup,
-      style: {
-        position: "absolute",
-        top: position.top,
-        left: position.left,
-        zIndex: 1001
-      },
+      ref: placement.setPopupEl,
+      className: placement.className,
+      style: placement.style,
       children: /* @__PURE__ */ jsxs("div", { className: pluginPickerClass.picker, children: [
         /* @__PURE__ */ jsx("div", { className: pluginPickerClass.search, children: mode === "commands" ? `/${query}` : `${selectedCommand ? `/${selectedCommand.name} ` : ""}${query}` }),
         loadingArgs && items.length === 0 ? /* @__PURE__ */ jsx("div", { className: pluginPickerClass.empty, children: "Loading..." }) : items.length === 0 ? /* @__PURE__ */ jsx("div", { className: pluginPickerClass.empty, children: emptyMessage }) : /* @__PURE__ */ jsx(
@@ -2803,6 +2882,7 @@ var SlashCommandMenuInner = forwardRef(function SlashCommandMenuInner2({
             id: listboxId,
             role: "listbox",
             "aria-activedescendant": activeOptionId,
+            className: pluginPickerClass.list,
             children: items.map((item, index) => {
               const active = index === selectedIndex;
               return /* @__PURE__ */ jsxs(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@railway/inkwell",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Inkwell is a Markdown editor and renderer for React with an extensible plugin system.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -63,6 +63,7 @@
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/mdast": "^4.0.4",
+    "@types/node": "^24.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^6.0.1",

package/src/styles.css

@@ -72,21 +72,34 @@
 .inkwell-editor-wrapper {
   position: relative;
 }
-.inkwell-editor {
-  min-height: 200px;
+
+/* Visual-chrome defaults (padding, border, background, type) are wrapped in
+   `:where()` so they carry 0,0,0 specificity. Any single-class consumer rule
+   on `.inkwell-editor` (Tailwind utilities, `classNames.editor`, etc.) wins
+   automatically — no `!important` or selector gymnastics needed.
+
+   Container size (min-height, max-height, height) is deliberately NOT
+   defaulted here. Inkwell sits inside the consumer's layout and the right
+   size is a consumer decision: a full-page editor wants `min-height: 60vh`,
+   a chat composer wants `min-height: 0`, a panel just wants to fill its
+   container. Set it on the editor via `styles.editor`, `classNames.editor`,
+   or your own CSS. */
+:where(.inkwell-editor) {
   padding: 1rem 1.25rem;
-  outline: none;
   border: 1px solid var(--inkwell-border);
   border-radius: var(--inkwell-radius);
   background: var(--inkwell-bg);
-  color: var(--inkwell-text);
   line-height: 1.6;
   font-size: 0.95rem;
   transition: border-color 0.15s ease;
 }
-.inkwell-editor:focus-within {
+:where(.inkwell-editor:focus-within) {
   border-color: var(--inkwell-border-strong);
 }
+.inkwell-editor {
+  outline: none;
+  color: var(--inkwell-text);
+}
 
 .inkwell-editor p {
   margin: 0;
@@ -183,7 +196,9 @@
   color: hsl(0, 75%, 55%);
   font-weight: 500;
 }
-.inkwell-editor-wrapper.inkwell-editor-has-character-limit .inkwell-editor {
+:where(
+    .inkwell-editor-wrapper.inkwell-editor-has-character-limit .inkwell-editor
+  ) {
   padding-right: 5.25rem;
   padding-bottom: 2.25rem;
 }
@@ -226,7 +241,7 @@
 
 .inkwell-plugin-bubble-menu-container {
   position: absolute;
-  z-index: 1100;
+  z-index: 9999;
 }
 .inkwell-plugin-bubble-menu-inner {
   display: flex;
@@ -303,6 +318,28 @@
 .inkwell-plugin-picker-search::placeholder {
   color: var(--inkwell-text-dim);
 }
+.inkwell-plugin-picker-list {
+  max-height: 240px;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  scrollbar-width: thin;
+  scrollbar-color: var(--inkwell-border-strong) transparent;
+}
+.inkwell-plugin-picker-list::-webkit-scrollbar {
+  width: 8px;
+}
+.inkwell-plugin-picker-list::-webkit-scrollbar-track {
+  background: transparent;
+}
+.inkwell-plugin-picker-list::-webkit-scrollbar-thumb {
+  background-color: var(--inkwell-border-strong);
+  border-radius: 4px;
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+.inkwell-plugin-picker-list::-webkit-scrollbar-thumb:hover {
+  background-color: var(--inkwell-text-dim);
+}
 .inkwell-plugin-picker-item {
   padding: 7px 10px;
   cursor: pointer;
@@ -348,9 +385,13 @@
 
 /* ── Renderer ────────────────────────────────────────────────────── */
 
-.inkwell-renderer {
+/* Layout defaults on the renderer follow the same low-specificity pattern
+   as the editor — a single-class consumer rule wins automatically. */
+:where(.inkwell-renderer) {
   line-height: 1.65;
   font-size: 0.95rem;
+}
+.inkwell-renderer {
   color: var(--inkwell-text);
 }
 .inkwell-renderer :first-child {