@octanejs/blocknote 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway and Octane contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# @octanejs/blocknote
+
+Headless [BlockNote](https://www.blocknotejs.org) editor for Octane. It covers the editor surface of `@blocknote/react@0.53.0` without the default UI, and uses `@blocknote/core` unchanged.
+
+## Install
+
+```bash
+npm install @octanejs/blocknote
+pnpm add @octanejs/blocknote
+```
+
+## Usage
+
+```tsx
+import { BlockNoteViewRaw, useCreateBlockNote } from '@octanejs/blocknote';
+
+export function Editor() @{
+	const editor = useCreateBlockNote({
+		initialContent: [{ type: 'paragraph', content: 'Hello' }],
+	});
+
+	<BlockNoteViewRaw editor={editor} onChange={() => console.log(editor.document)} />
+}
+```
+
+`BlockNoteViewRaw` imports `@blocknote/core/style.css`. Toolbars, menus, and other UI are yours to build. Render them as children, read the editor with `useBlockNoteEditor()`, and use `renderEditor={false}` with `<BlockNoteViewEditor />` to control where the editable area goes.
+
+## Exports
+
+- `BlockNoteViewRaw`, `BlockNoteViewEditor`, `BlockNoteViewProps`
+- `BlockNoteContext`, `useBlockNoteContext`, `BlockNoteContextValue`
+- `useCreateBlockNote`, `useBlockNoteEditor`
+- `useEditorChange`, `useEditorSelectionChange`, `usePrefersColorScheme`
+- `PortalElementsMap`, `PortalTarget`
+
+## Building UI
+
+This package has no default UI. Each BlockNote menu and toolbar is a framework-neutral `@blocknote/core` extension that exposes a store. The store has `subscribe(listener)` and `state`, so Octane's own `useSyncExternalStore` can read it without any extra dependency.
+
+### Menus and toolbars
+
+```tsx
+import { SuggestionMenu, filterSuggestionItems, getDefaultSlashMenuItems } from '@blocknote/core';
+import { useBlockNoteEditor } from '@octanejs/blocknote';
+import { useEffect, useSyncExternalStore } from 'octane';
+
+export function SlashMenu() @{
+	const editor = useBlockNoteEditor();
+	const menu = editor.getExtension(SuggestionMenu)!;
+
+	useEffect(() => {
+		menu.addSuggestionMenu({ triggerCharacter: '/' });
+		return () => menu.removeSuggestionMenu('/');
+	}, [menu]);
+
+	const state = useSyncExternalStore(menu.store.subscribe, () => menu.store.state);
+	const items = state?.show
+		? filterSuggestionItems(getDefaultSlashMenuItems(editor), state.query)
+		: [];
+
+	@if (state?.show) {
+		<ul
+			class="slash-menu"
+			style={{ position: 'fixed', left: state.referencePos.left, top: state.referencePos.bottom }}
+		>
+			@for (const item of items; key item.key) {
+				<li
+					onMouseDown={(event: MouseEvent) => {
+						event.preventDefault(); // keep focus in the editor
+						menu.clearQuery();
+						menu.closeMenu();
+						item.onItemClick();
+					}}
+				>
+					{item.title}
+				</li>
+			}
+		</ul>
+	}
+}
+
+// <BlockNoteViewRaw editor={editor}><SlashMenu /></BlockNoteViewRaw>
+```
+
+`FormattingToolbar`, `SideMenu`, `LinkToolbar`, `FilePanel`, and `TableHandles` follow the same pattern. For collision-aware placement, position the element from `referencePos` with a library such as `@octanejs/floating-ui`.
+
+The extension stores are TanStack Stores. If your app already uses `@octanejs/tanstack-store`, `useStore(menu.store, (state) => state?.query)` also works and adds selector-based updates.
+
+### Custom blocks
+
+Core's `createBlockSpec` renders to DOM. To render an Octane component inside a block, mount a root on a node you own and unmount it in `destroy`:
+
+```tsx
+import { BlockNoteSchema, createBlockSpec, defaultBlockSpecs } from '@blocknote/core';
+import { createRoot } from 'octane';
+
+function CalloutIcon(props: { emoji: string }) @{
+	<span class="callout-icon">{props.emoji}</span>
+}
+
+const Callout = createBlockSpec(
+	{ type: 'callout', propSchema: { emoji: { default: '💡' } }, content: 'inline' },
+	{
+		render: (block) => {
+			const dom = document.createElement('div');
+			const icon = document.createElement('span');
+			const contentDOM = document.createElement('div');
+			dom.className = 'callout';
+			icon.contentEditable = 'false';
+			dom.append(icon, contentDOM);
+			const root = createRoot(icon);
+			root.render(CalloutIcon, { emoji: block.props.emoji });
+			return { dom, contentDOM, destroy: () => root.unmount() };
+		},
+	},
+);
+
+export const schema = BlockNoteSchema.create({
+	blockSpecs: { ...defaultBlockSpecs, callout: Callout() },
+});
+
+// useCreateBlockNote({ schema })
+```
+
+Each block root is separate from your app tree, so it does not see your contexts (theme, router, stores). Pass what it needs through props or module state. Context-aware block and inline content specs are planned.
+
+Both recipes run as real-browser tests in `tests/browser/harness`.
+
+## Server rendering
+
+Server rendering is supported. The server emits the view shell, and the editor mounts into it on the client after hydration. Document content is not part of the server HTML. Without a `theme` prop the server renders the light scheme, and the system scheme applies after hydration. Pass `theme` to fix it on both sides.
+
+## Known differences
+
+- No default UI. `BlockNoteView`, `BlockNoteDefaultUI`, `ComponentsContext`, and the toolbar, menu, side-menu, table-handle, and comment components are not provided. Upstream disables all of them when no components context exists, so `BlockNoteViewRaw` here matches that upstream configuration.
+- `BlockNoteViewRaw` does not accept the default UI flags (`formattingToolbar`, `slashMenu`, and so on). `portalElements` reads only `default`.
+- Custom React block, inline content, and style specs are not provided.
+- Event handlers receive native DOM events, as everywhere in Octane.
+
+## Provenance
+
+Independently authored and MIT licensed. See [UPSTREAM.md](./UPSTREAM.md).

package/UPSTREAM.md

@@ -0,0 +1,41 @@
+# Upstream provenance
+
+`@octanejs/blocknote` provides the headless editor surface of `@blocknote/react@0.53.0` for Octane.
+
+| Field                    | Pin                                                                                                   |
+| ------------------------ | ----------------------------------------------------------------------------------------------------- |
+| Package                  | `@blocknote/react`                                                                                    |
+| Version                  | `0.53.0` exactly                                                                                      |
+| Repository               | `https://github.com/TypeCellOS/BlockNote`                                                             |
+| Release commit (gitHead) | `d5e8c96e2ad5f6832da60bc3c9acd3f6c16c25c5`                                                            |
+| npm integrity            | `sha512-W8HHfKnt3mf2ugb1n9XAsjR7XAAX4GdZl+SE3h4DPcHdTnpfQCX7B2+tIP6CFKm6jW+BUZ2Y2fpDrLgJEtGtGw==`     |
+| Framework-neutral core   | `@blocknote/core@0.53.0` (runtime dependency, MPL-2.0, not vendored)                                  |
+
+## Source boundary and licensing
+
+`@blocknote/react` is licensed MPL-2.0, which is outside this repository's
+approved copy list (MIT, Unlicense, BSD-3-Clause, Apache-2.0). No upstream
+source, declaration, stylesheet, or test is vendored, copied, or adapted here.
+
+The Octane adapter is independently authored and MIT licensed. It was written
+from a behavior and API contract derived from BlockNote's public documentation
+and public API names, by an implementer who did not read the `@blocknote/react`
+source. `@blocknote/core` stays an ordinary MPL-2.0 dependency and supplies the
+editor, schemas, and `@blocknote/core/style.css`.
+
+An earlier private scaffold of this package was generated by mechanically
+copying upstream source. That scaffold was removed in full before this surface
+was written.
+
+## Supported surface
+
+Headless only: `BlockNoteViewRaw`, `BlockNoteViewEditor`, `BlockNoteContext`,
+`useBlockNoteContext`, `useCreateBlockNote`, `useBlockNoteEditor`,
+`useEditorChange`, `useEditorSelectionChange`, and `usePrefersColorScheme`.
+This matches upstream `BlockNoteViewRaw` rendered without a components context,
+where every default UI element is disabled.
+
+Not provided: the default UI (`BlockNoteView` from UI-kit packages,
+`BlockNoteDefaultUI`, `ComponentsContext`, toolbars, menus, side menu, table
+handles, comments), custom React block/inline/style specs, and the
+`@blocknote/react/style.css` stylesheet.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@octanejs/blocknote",
+  "devDependencies": {
+    "@blocknote/react": "0.53.0",
+    "@tsrx/react": "^0.3.7",
+    "esbuild": "^0.28.1",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "vitest": "^4.1.10",
+    "octane": "0.5.0"
+  },
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "description": "BlockNote for the octane renderer — an Octane binding for @blocknote/react block-based rich text editors.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/blocknote"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "UPSTREAM.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@blocknote/core": "0.53.0"
+  },
+  "peerDependencies": {
+    "octane": "^0.5.0"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "scripts": {
+    "typecheck": "tsrx-tsc --noEmit -p tsconfig.supported.json",
+    "test": "vitest run --root ../.. --project blocknote"
+  }
+}

package/src/BlockNoteContext.ts

@@ -0,0 +1,39 @@
+// Independently authored Octane adapter for the public @blocknote/react 0.53.0 API.
+import type {
+	BlockNoteEditor,
+	BlockNoteSchema,
+	BlockSchema,
+	DefaultBlockSchema,
+	DefaultInlineContentSchema,
+	DefaultStyleSchema,
+	InlineContentSchema,
+	StyleSchema,
+} from '@blocknote/core';
+import { createContext, useContext } from 'octane';
+
+/** The value a `BlockNoteViewRaw` shares with its descendants. */
+export type BlockNoteContextValue<
+	B extends BlockSchema = DefaultBlockSchema,
+	I extends InlineContentSchema = DefaultInlineContentSchema,
+	S extends StyleSchema = DefaultStyleSchema,
+> = {
+	editor?: BlockNoteEditor<B, I, S>;
+	colorSchemePreference?: 'light' | 'dark';
+	setContentEditableProps?: (props: Record<string, any> | undefined) => void;
+};
+
+export const BlockNoteContext = createContext<BlockNoteContextValue<any, any, any> | undefined>(
+	undefined,
+);
+
+/**
+ * Read the nearest BlockNote context. The optional schema only narrows the
+ * returned editor type; it is not checked at runtime.
+ */
+export function useBlockNoteContext<
+	B extends BlockSchema = DefaultBlockSchema,
+	I extends InlineContentSchema = DefaultInlineContentSchema,
+	S extends StyleSchema = DefaultStyleSchema,
+>(_schema?: BlockNoteSchema<B, I, S>): BlockNoteContextValue<B, I, S> | undefined {
+	return useContext(BlockNoteContext) as BlockNoteContextValue<B, I, S> | undefined;
+}

package/src/BlockNoteViewRaw.tsrx

@@ -0,0 +1,188 @@
+// Independently authored Octane adapter for the public @blocknote/react 0.53.0 API.
+import '@blocknote/core/style.css';
+
+import type {
+	BlockNoteEditor,
+	BlockSchema,
+	DefaultBlockSchema,
+	DefaultInlineContentSchema,
+	DefaultStyleSchema,
+	InlineContentSchema,
+	StyleSchema,
+} from '@blocknote/core';
+import {
+	createContext,
+	type OctaneNode,
+	useCallback,
+	useContext,
+	useEffect,
+	useMemo,
+	useState,
+} from 'octane';
+import type { Octane } from 'octane/jsx-runtime';
+
+import {
+	BlockNoteContext,
+	type BlockNoteContextValue,
+	useBlockNoteContext,
+} from './BlockNoteContext';
+import { useEditorChange } from './hooks/useEditorChange';
+import { useEditorSelectionChange } from './hooks/useEditorSelectionChange';
+import { usePrefersColorScheme } from './hooks/usePrefersColorScheme';
+import { type PortalElementsMap, resolvePortalTarget } from './portalTarget';
+
+export type BlockNoteViewProps<
+	B extends BlockSchema = DefaultBlockSchema,
+	I extends InlineContentSchema = DefaultInlineContentSchema,
+	S extends StyleSchema = DefaultStyleSchema,
+> =
+	{
+		editor: BlockNoteEditor<B, I, S>;
+		theme?: 'light' | 'dark';
+		/** @default true */
+		editable?: boolean;
+		onChange?: Parameters<BlockNoteEditor<B, I, S>['onChange']>[0];
+		onSelectionChange?: () => void;
+		/**
+ * Render the editable surface as the container's first child. Set to
+ * `false` to place `BlockNoteViewEditor` among `children` yourself.
+ * @default true
+ */
+		renderEditor?: boolean;
+		autoFocus?: boolean;
+		portalElements?: PortalElementsMap;
+		className?: string;
+		children?: OctaneNode;
+		ref?: React.Ref<HTMLDivElement>;
+	} & Omit<
+		Octane.HTMLAttributes<HTMLDivElement>,
+		'onChange' | 'onSelectionChange' | 'children' | 'class' | 'className'
+	>;
+
+/** What `BlockNoteViewRaw` hands to the `BlockNoteViewEditor` it contains. */
+type ViewEditorSettings = {
+	autoFocus: boolean | undefined;
+	editable: boolean | undefined;
+	portalTarget: HTMLElement | null;
+	contentEditableProps: Record<string, any> | undefined;
+};
+
+const ViewEditorContext = createContext<ViewEditorSettings | undefined>(undefined);
+
+const ignore = () => {};
+
+export function BlockNoteViewRaw<
+	B extends BlockSchema = DefaultBlockSchema,
+	I extends InlineContentSchema = DefaultInlineContentSchema,
+	S extends StyleSchema = DefaultStyleSchema,
+>(props: BlockNoteViewProps<B, I, S>) @{
+	const {
+		editor,
+		theme,
+		editable,
+		onChange,
+		onSelectionChange,
+		renderEditor,
+		autoFocus,
+		portalElements,
+		className,
+		children,
+		ref,
+		...rest
+	} = props;
+
+	const outerContext = useBlockNoteContext();
+	const systemColorScheme = usePrefersColorScheme();
+	const scheme: 'light' | 'dark' =
+		theme ?? outerContext?.colorSchemePreference ??
+			(systemColorScheme === 'dark' ? 'dark' : 'light');
+
+	const [contentEditableProps, setContentEditableProps] = useState<Record<string, any> | undefined>(
+		undefined,
+	);
+
+	useEditorChange((onChange ?? ignore) as Parameters<typeof useEditorChange>[0], editor);
+	useEditorSelectionChange(onSelectionChange ?? ignore, editor);
+
+	useEffect(() => {
+		const portalElement = editor.portalElement;
+		if (!portalElement) {
+			throw new Error('Portal element not found');
+		}
+
+		portalElement.className = className ? `bn-root ${scheme} ${className}` : `bn-root ${scheme}`;
+		portalElement.setAttribute('data-color-scheme', scheme);
+	}, [editor, scheme, className]);
+
+	const portalTargetOption = portalElements?.default;
+	const portalTarget = useMemo(() => resolvePortalTarget(portalTargetOption), [portalTargetOption]);
+
+	const contextValue = useMemo<BlockNoteContextValue<B, I, S>>(
+		() => ({
+			...outerContext,
+			editor,
+			colorSchemePreference: scheme,
+			setContentEditableProps,
+		}),
+		[outerContext, editor, scheme, setContentEditableProps],
+	);
+
+	const settings = useMemo<ViewEditorSettings>(
+		() => ({ autoFocus, editable, portalTarget, contentEditableProps }),
+		[autoFocus, editable, portalTarget, contentEditableProps],
+	);
+
+	<BlockNoteContext value={contextValue}>
+		<ViewEditorContext value={settings}>
+			<div
+				{...rest}
+				class={['bn-root bn-container', scheme, className]}
+				data-color-scheme={scheme}
+				ref={ref ?? null}
+			>
+				@if (renderEditor !== false) {
+					<BlockNoteViewEditor>{children}</BlockNoteViewEditor>
+				} @else {
+					<>
+						{children}
+					</>
+				}
+			</div>
+		</ViewEditorContext>
+	</BlockNoteContext>
+}
+
+/** The editable surface. Renders only inside a `BlockNoteViewRaw`. */
+export function BlockNoteViewEditor(props: { children?: OctaneNode }) @{
+	const settings = useContext(ViewEditorContext);
+	const editor = useBlockNoteContext()?.editor;
+
+	if (!settings || !editor) {
+		throw new Error('BlockNoteViewEditor must be rendered inside a BlockNoteViewRaw component');
+	}
+
+	const { autoFocus, editable, portalTarget, contentEditableProps } = settings;
+
+	// A new callback identity detaches the old ref (unmount) and attaches the new
+	// one (mount). Remounting on `editable` changes is deliberate: TipTap drops the
+	// host's tabIndex when editability flips on a mounted view.
+	const mountEditor = useCallback((element: HTMLDivElement | null) => {
+		editor.isEditable = editable !== false;
+		if (element) {
+			editor.mount(element, { portalTarget });
+		} else {
+			editor.unmount();
+		}
+	}, [editable, editor, portalTarget]);
+
+	<>
+		<div
+			aria-autocomplete="list"
+			aria-haspopup="listbox"
+			data-bn-autofocus={autoFocus}
+			{...contentEditableProps}
+			ref={mountEditor}
+		/>
+		{props.children}
+	</>
+}

package/src/hooks/useBlockNoteEditor.ts

@@ -0,0 +1,33 @@
+// Independently authored Octane adapter for the public @blocknote/react 0.53.0 API.
+import type {
+	BlockNoteEditor,
+	BlockNoteSchema,
+	BlockSchema,
+	DefaultBlockSchema,
+	DefaultInlineContentSchema,
+	DefaultStyleSchema,
+	InlineContentSchema,
+	StyleSchema,
+} from '@blocknote/core';
+
+import { useBlockNoteContext } from '../BlockNoteContext';
+import { splitSlot } from '../internal';
+
+/** Read the editor from the nearest `BlockNoteViewRaw` or `BlockNoteContext`. */
+export function useBlockNoteEditor<
+	B extends BlockSchema = DefaultBlockSchema,
+	I extends InlineContentSchema = DefaultInlineContentSchema,
+	S extends StyleSchema = DefaultStyleSchema,
+>(schema?: BlockNoteSchema<B, I, S>): BlockNoteEditor<B, I, S>;
+export function useBlockNoteEditor(...args: unknown[]): BlockNoteEditor<any, any, any> {
+	const [userArgs] = splitSlot(args);
+	const context = useBlockNoteContext(userArgs[0] as BlockNoteSchema<any, any, any> | undefined);
+
+	if (!context?.editor) {
+		throw new Error(
+			'useBlockNoteEditor was called outside of a BlockNoteContext provider or BlockNoteViewRaw component',
+		);
+	}
+
+	return context.editor;
+}

package/src/hooks/useCreateBlockNote.ts

@@ -0,0 +1,37 @@
+// Independently authored Octane adapter for the public @blocknote/react 0.53.0 API.
+import {
+	BlockNoteEditor,
+	type BlockNoteEditorOptions,
+	type CustomBlockNoteSchema,
+	type DefaultBlockSchema,
+	type DefaultInlineContentSchema,
+	type DefaultStyleSchema,
+} from '@blocknote/core';
+import { useMemo } from 'octane';
+
+import { splitSlot, subSlot } from '../internal';
+
+type DependencyList = readonly unknown[];
+
+const noDeps: DependencyList = [];
+
+/** Create a BlockNote editor once, or again whenever `deps` change. */
+export function useCreateBlockNote<
+	Options extends Partial<BlockNoteEditorOptions<any, any, any>> | undefined,
+>(
+	options?: Options,
+	deps?: DependencyList,
+): Options extends { schema: CustomBlockNoteSchema<infer B, infer I, infer S> }
+	? BlockNoteEditor<B, I, S>
+	: BlockNoteEditor<DefaultBlockSchema, DefaultInlineContentSchema, DefaultStyleSchema>;
+export function useCreateBlockNote(...args: unknown[]): BlockNoteEditor<any, any, any> {
+	const [userArgs, slot] = splitSlot(args);
+	const options = userArgs[0] as Partial<BlockNoteEditorOptions<any, any, any>> | undefined;
+	const deps = (userArgs[1] as DependencyList | undefined) ?? noDeps;
+
+	return useMemo(
+		() => BlockNoteEditor.create(options ?? {}),
+		deps as unknown[],
+		subSlot(slot, 'create'),
+	);
+}

package/src/hooks/useEditorChange.ts

@@ -0,0 +1,28 @@
+// Independently authored Octane adapter for the public @blocknote/react 0.53.0 API.
+import type { BlockNoteEditor } from '@blocknote/core';
+import { useEffect } from 'octane';
+
+import { useBlockNoteContext } from '../BlockNoteContext';
+import { splitSlot, subSlot } from '../internal';
+
+type ChangeCallback = Parameters<BlockNoteEditor<any, any, any>['onChange']>[0];
+
+/** Subscribe to content changes of `editor`, or of the context editor when omitted. */
+export function useEditorChange(
+	callback: ChangeCallback,
+	editor?: BlockNoteEditor<any, any, any>,
+): void;
+export function useEditorChange(...args: unknown[]): void {
+	const [userArgs, slot] = splitSlot(args);
+	const callback = userArgs[0] as ChangeCallback;
+	const context = useBlockNoteContext();
+	const editor = (userArgs[1] as BlockNoteEditor<any, any, any> | undefined) ?? context?.editor;
+
+	if (!editor) {
+		throw new Error(
+			'useEditorChange was called outside of a BlockNoteContext provider or BlockNoteViewRaw component',
+		);
+	}
+
+	useEffect(() => editor.onChange(callback), [editor, callback], subSlot(slot, 'subscribe'));
+}

package/src/hooks/useEditorSelectionChange.ts

@@ -0,0 +1,32 @@
+// Independently authored Octane adapter for the public @blocknote/react 0.53.0 API.
+import type { BlockNoteEditor } from '@blocknote/core';
+import { useEffect } from 'octane';
+
+import { useBlockNoteContext } from '../BlockNoteContext';
+import { splitSlot, subSlot } from '../internal';
+
+/** Subscribe to selection changes of `editor`, or of the context editor when omitted. */
+export function useEditorSelectionChange(
+	callback: () => void,
+	editor?: BlockNoteEditor<any, any, any>,
+	includeSelectionChangedByRemote?: boolean,
+): void;
+export function useEditorSelectionChange(...args: unknown[]): void {
+	const [userArgs, slot] = splitSlot(args);
+	const callback = userArgs[0] as () => void;
+	const includeSelectionChangedByRemote = userArgs[2] as boolean | undefined;
+	const context = useBlockNoteContext();
+	const editor = (userArgs[1] as BlockNoteEditor<any, any, any> | undefined) ?? context?.editor;
+
+	if (!editor) {
+		throw new Error(
+			'useEditorSelectionChange was called outside of a BlockNoteContext provider or BlockNoteViewRaw component',
+		);
+	}
+
+	useEffect(
+		() => editor.onSelectionChange(callback, includeSelectionChangedByRemote),
+		[editor, callback, includeSelectionChangedByRemote],
+		subSlot(slot, 'subscribe'),
+	);
+}

package/src/hooks/usePrefersColorScheme.ts

@@ -0,0 +1,54 @@
+// Independently authored Octane adapter for the public @blocknote/react 0.53.0 API.
+import { useSyncExternalStore } from 'octane';
+
+import { splitSlot, subSlot } from '../internal';
+
+export type ColorSchemePreference = 'dark' | 'light' | 'no-preference';
+
+const darkQuery = '(prefers-color-scheme: dark)';
+const lightQuery = '(prefers-color-scheme: light)';
+
+function readPreference(): ColorSchemePreference {
+	if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+		return 'no-preference';
+	}
+
+	if (window.matchMedia(darkQuery).matches) {
+		return 'dark';
+	}
+
+	return window.matchMedia(lightQuery).matches ? 'light' : 'no-preference';
+}
+
+function subscribe(onChange: () => void): () => void {
+	if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+		return () => {};
+	}
+
+	const queries = [window.matchMedia(darkQuery), window.matchMedia(lightQuery)];
+	for (const query of queries) {
+		query.addEventListener('change', onChange);
+	}
+	return () => {
+		for (const query of queries) {
+			query.removeEventListener('change', onChange);
+		}
+	};
+}
+
+// The server cannot see the media query. Hydration renders this snapshot too,
+// so server HTML and the first client render agree; the store then re-reads
+// the live preference after hydration.
+const serverPreference = (): ColorSchemePreference => 'no-preference';
+
+/** Track the system `prefers-color-scheme` media query. */
+export function usePrefersColorScheme(): ColorSchemePreference;
+export function usePrefersColorScheme(...args: unknown[]): ColorSchemePreference {
+	const [, slot] = splitSlot(args);
+	return useSyncExternalStore(
+		subscribe,
+		readPreference,
+		serverPreference,
+		subSlot(slot, 'preference'),
+	);
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// Independently authored Octane adapter for the public @blocknote/react 0.53.0 API.
+export {
+	BlockNoteContext,
+	useBlockNoteContext,
+	type BlockNoteContextValue,
+} from './BlockNoteContext';
+export {
+	BlockNoteViewRaw,
+	BlockNoteViewEditor,
+	type BlockNoteViewProps,
+} from './BlockNoteViewRaw.tsrx';
+export type { PortalElementsMap, PortalTarget } from './portalTarget';
+export { useCreateBlockNote } from './hooks/useCreateBlockNote';
+export { useBlockNoteEditor } from './hooks/useBlockNoteEditor';
+export { useEditorChange } from './hooks/useEditorChange';
+export { useEditorSelectionChange } from './hooks/useEditorSelectionChange';
+export { usePrefersColorScheme } from './hooks/usePrefersColorScheme';

package/src/internal.ts

@@ -0,0 +1,18 @@
+// Independently authored Octane adapter for the public @blocknote/react 0.53.0 API.
+// Slot mechanics for @octanejs/blocknote's plain-`.ts` hooks. The Octane
+// compiler appends a per-call-site Symbol as the final argument of every
+// custom-hook call; these helpers separate it from the public arguments and
+// derive one stable sub-slot per base hook a binding hook composes.
+
+import { createSubSlot } from 'octane';
+
+export const subSlot = createSubSlot({
+	tagPrefix: ':@octanejs/blocknote:',
+	slotlessPrefix: '@octanejs/blocknote:',
+});
+
+/** Split a compiler-owned trailing slot from a custom hook's user arguments. */
+export function splitSlot(args: readonly unknown[]): [readonly unknown[], symbol | undefined] {
+	const tail = args.at(-1);
+	return typeof tail === 'symbol' ? [args.slice(0, -1), tail] : [args, undefined];
+}

package/src/portalTarget.ts

@@ -0,0 +1,33 @@
+// Independently authored Octane adapter for the public @blocknote/react 0.53.0 API.
+/** Where floating UI portals mount: an element, a CSS selector, or `null` for `document.body`. */
+export type PortalTarget = HTMLElement | string | null;
+
+export type PortalElementsMap = {
+	default?: PortalTarget;
+};
+
+/**
+ * Resolve a public portal target to the element `editor.mount` expects.
+ * `undefined` yields `null`, which lets `mount` pick its own default.
+ */
+export function resolvePortalTarget(target: PortalTarget | undefined): HTMLElement | null {
+	if (target === undefined || typeof document === 'undefined') {
+		return null;
+	}
+
+	if (target === null) {
+		return document.body;
+	}
+
+	if (typeof target !== 'string') {
+		return target;
+	}
+
+	const element = document.querySelector<HTMLElement>(target);
+	if (element === null) {
+		console.warn(
+			`@octanejs/blocknote: portal target "${target}" matched no element; using the default portal target.`,
+		);
+	}
+	return element;
+}