@neta-art/cohub 12.2.0 → 12.4.0

package/README.md

@@ -112,7 +112,7 @@ const created = await space.boards.create({
   },
 });
 
-const board = space.board(created.id);
+const board = space.board(created.id); // or await space.boards.open("boards/plan.board")
 const { items, version } = await board.get({ only: ["items"] });
 await board.apply({ items: { goal: { props: { text: "Shipped" } } } }, { baseVersion: version });
 
@@ -159,7 +159,7 @@ change, so they work directly with `useSyncExternalStore`:
 ```ts
 import { createBoardRegistry, defineBoardItem, worldPoint } from "@neta-art/cohub/board";
 import { createBoardEditor } from "@neta-art/cohub/board/editor";
-import { createBoardReplica } from "@neta-art/cohub/board/replica";
+import { createBoardReplica, createIndexedDbBoardReplicaStorage } from "@neta-art/cohub/board/replica";
 import { createBoardAssetManager, mountBoardStage } from "@neta-art/cohub/board/stage";
 import { z } from "zod";
 
@@ -172,7 +172,13 @@ const order = defineBoardItem({
   capabilities: { canRotate: false },
 });
 
-const replica = createBoardReplica({ remote: space.board(boardId) });
+// Cached documents and unsent writes survive a reload; clear them on sign-out
+// with `clearBoardReplicaStorage({ userKey })`. The replica reads the Board again
+// after a realtime reconnect and resends pending writes when the network returns.
+const replica = createBoardReplica({
+  remote: space.board(boardId),
+  storage: createIndexedDbBoardReplicaStorage({ userKey, spaceId: space.id, boardId }),
+});
 await replica.start();
 
 const editor = createBoardEditor({
@@ -230,6 +236,84 @@ rewritten by older ones. For a canvas look instead of DOM, pass renderers to
 `createBoardCardRendererResolver` from `board/render` and hand the result to
 the stage or to `renderBoardExport` as `renderers`.
 
+### Hosting a Board
+
+Compose the SDK instead of wrapping it, and each release's loading, level of
+detail and text work reaches your Board without code changes.
+
+Pictures your own items show go through `itemAsset`. They share the built-in
+loader: CDN variants sized to the screen, loads ordered by where the view is
+heading, prefetch, compact copies when panned away, device budgets, one cache
+and exports. `src` is a Space path, resolved like an image item's, or a URL;
+`fit: "cover"` sizes pictures cropped to fill their box by the short edge. Call
+`invalidateItemAssets()` when the data it reads changes, and `invalidatePath`
+when a file changes:
+
+```ts
+const assets = createBoardAssetManager({
+  resolveFileUrl: source.resolveFileUrl,
+  // undefined keeps the built-in rule; null shows no picture.
+  itemAsset: (item) => {
+    if (item.type !== "acme.order") return undefined;
+    const cover = covers.get(item.props.orderId as string); // "orders/o-1.webp"
+    return cover ? { src: cover, fit: "cover" } : null;
+  },
+});
+```
+
+- **Budgets.** Leave `lod`, `prefetch`, `concurrency` and `lruBudget` unset; they
+  follow `defaultBoardDeviceBudget()`. Force a tier with
+  `boardDeviceBudget(readBoardDeviceSignals(), "low")`.
+- **Canvas cards.** Declare `lod` (`{ kind: "media" }` for pictures) and
+  `renderFar`, drawn with `drawFarPlate(graphics, item.frame, { fill:
+  farPictureTone(item, context) ?? paper })`. Wrap card text with
+  `layoutTextLines(text, font, width, { whiteSpace: "normal", maxLines: 2 })`
+  and apply `context.textResolution` in the `resolution` hook.
+- **Opening cards.** Give a type `activation: "tap"` and handle `onActivate`: a
+  quick press opens the card without selecting it, a drag moves it (or pans with
+  the hand tool or read-only), and hovering shows a pointer instead of ports. A
+  press held in place past `BOARD_TAP_MAX_MS` does nothing: it was a pick-up. A
+  press on a selected card reports `selected: true`. `onLongPress` fires for a still
+  touch or pen; call `editor.pickUp()` there to pick the card up and drag it. The
+  stage drops the click a touch screen sends after a tap that opened something.
+- **Card keys.** A renderer's `hitAt(item, point, context)` returns `{ action, cursor? }`
+  for keys it draws; the stage shows the cursor, passes the hovered key to renderers as
+  `context.hoveredHit` and sends presses to `onHit` (return `false` to let the editor
+  have them). Media cards report `BOARD_PLAY_MEDIA` this way. `handlesHit(item, action)`
+  names the keys you act on; the rest show no cursor and go to the editor.
+- **Touch.** A touch on the selected item drags it, never a port. Pass
+  `touchRotation: false` to `createBoardEditor` to move and resize by touch and pen
+  without a rotation handle.
+- **DOM views.** `viewLayer: "below"` puts them under the canvas, so selection and
+  strokes draw over them; views there get no input. Use a theme with `imageBackground`
+  and paint the Board background behind the host, or the canvas covers them.
+- **Previews.** Write `preview: { title, excerpt, cover, src }` on your items so
+  clients without your renderer, exports and agents show them as cards. Keep it out
+  of undo with `editor.commitPatch(patch, { record: false })`.
+- **Text editing.** Place the in-place editor with `boardTextEditLayout`, so its
+  caret sits on the canvas text:
+
+  ```ts
+  const layout = boardTextEditLayout(item, { viewport: editor.camera, scene: editor.scene, style: stage.theme.style, draft });
+  // A content-box textarea at layout.left/top, sized layout.width × height, padded by
+  // layout.padding, with `rotate(${layout.rotation}deg) scale(${layout.scale})` about its center.
+  ```
+
+- **Themes.** Start from a built-in theme and override what differs:
+  `{ key: "neta-pixel", ...boardRenderTheme("neta-pixel") }`. `style.frameLabelSize`
+  sets frame titles; the editor's title hit box and text editor follow it.
+- **Fonts.** Board text measures in `"Geist Variable"`; load
+  `@fontsource-variable/geist` so lines match the CLI export.
+- **Agent context.** `onViewStateChange` on the editor reports `visibleRect` and
+  `selectedNodes`; send them with a prompt as
+  `buildViewportContentBlock([{ kind: "board", path, boardId, visibleRect, selectedNodes }])`
+  so the agent knows which Board, where and what the user is looking at.
+- **Measuring.** `runBoardStageBench(stage)` drives the stage with wheel input and
+  reports frame and settle times; `stage.stats()` shows live, far and texture counts.
+
+Release notes for Board changes end with `Hosts:`, naming what an embedding app
+must change, or `Hosts: no action`.
+
 ### Images
 
 In the browser, `renderBoardExport(renderer, document, options)` from

package/dist/board/editor/context.d.ts

@@ -84,6 +84,8 @@ type BoardEditorOptions = {
   initialTool?: BoardToolId;
   key?: string;
   readonly?: boolean;
+  /** false: touch and pen move and resize the selection but never rotate it. */
+  touchRotation?: boolean;
   preferences?: Partial<BoardEditorPreferences>;
   onPreferencesChange?: (preferences: BoardEditorPreferences) => void;
   onCommit: (patch: BoardPatch) => void | Promise<void>;

package/dist/board/editor/document.d.ts

@@ -15,7 +15,9 @@ declare function createDocumentModule(ctx: EditorContext): {
   readonly hasScriptItems: boolean;
   setScriptItems: (items: ReadonlyMap<string, BoardItem>) => void;
   animationItems: () => Map<string, BoardItem>;
-  commitPatch: (patch: BoardPatch) => Promise<void> | undefined;
+  commitPatch: (patch: BoardPatch, { record }?: {
+    record?: boolean;
+  }) => Promise<void> | undefined;
   rescene: (ids?: Iterable<string>) => void;
   reset: (next: BoardDocument) => void;
   setDraftItem: (id: string, item: BoardItem | null) => void;

package/dist/board/editor/document.js

@@ -206,7 +206,7 @@ function createDocumentModule(ctx) {
 		for (const [id, item] of changes) setDraftItem(id, item);
 		commit({}, record);
 	}
-	function commitPatch(patch) {
+	function commitPatch(patch, { record = true } = {}) {
 		if (options.readonly) throw new Error("Board is read-only.");
 		const before = state.base;
 		const result = applyBoardPatchToDocument(before, patch);
@@ -214,11 +214,13 @@ function createDocumentModule(ctx) {
 		const ids = Object.keys(patch.items ?? {});
 		const redo = diffBoardEdits(before, result.document, ids);
 		if (isEmptyBoardPatch(redo)) return;
-		state.undoStack = [...state.undoStack.slice(-199), {
-			undo: diffBoardEdits(result.document, before, ids),
-			redo
-		}];
-		state.redoStack = [];
+		if (record) {
+			state.undoStack = [...state.undoStack.slice(-199), {
+				undo: diffBoardEdits(result.document, before, ids),
+				redo
+			}];
+			state.redoStack = [];
+		}
 		adopt(result.document, ids);
 		return send(redo).then((error) => {
 			if (error) throw error;

package/dist/board/editor/editor.d.ts

@@ -11,7 +11,7 @@ import "../model/index.js";
 import { AlignMode, DistributeAxis } from "./align.js";
 import { BoardFocusOptions } from "./camera.js";
 import { BoardSelectionTransform, BoardTransformControl } from "./selection-transform.js";
-import { BoardInteraction, BoardPointerEvent, BoardTransformEnd } from "./interaction.js";
+import { BoardActivation, BoardInteraction, BoardPointerEvent, BoardTransformEnd } from "./interaction.js";
 import { BoardAppMetadata, BoardTaskSource } from "./creation.js";
 import { BoardClipboardPayload } from "./clipboard.js";
 import { BoardNaturalSize } from "./snapshots.js";
@@ -136,11 +136,13 @@ declare function createBoardEditor(options: BoardEditorOptions): {
   setPlayedItems: (items: ReadonlyMap<string, BoardItem>) => void;
   setScriptItems: (items: ReadonlyMap<string, BoardItem>) => void;
   animationItems: () => Map<string, BoardItem>;
-  commitPatch: (patch: BoardPatch) => Promise<void> | undefined;
+  commitPatch: (patch: BoardPatch, { record }?: {
+    record?: boolean;
+  }) => Promise<void> | undefined;
   consumeRecentlyAdded: () => string[];
   itemAt: (point: WorldPoint, exclude?: ReadonlySet<string> | undefined, includeTemporary?: boolean | undefined) => BoardSceneItem | null;
   itemById: (id: string) => BoardSceneItem | null;
-  labelItemAt: (point: WorldPoint) => BoardSceneItem | null;
+  labelItemAt: (point: WorldPoint, frameLabelSize?: number | undefined) => BoardSceneItem | null;
   idsInRect: (rect: Rect, includeTemporary?: boolean | undefined) => string[];
   setCamera: (viewport: BoardViewport) => void;
   setCameraPolicy: (policy: BoardCameraPolicy) => void;
@@ -219,6 +221,8 @@ declare function createBoardEditor(options: BoardEditorOptions): {
   pointerUp: (event: BoardPointerEvent) => void;
   pointerLeave: () => void;
   subscribeTransforms: (listener: (event: BoardTransformEnd) => void) => () => void;
+  subscribeActivations: (listener: (event: BoardActivation) => void) => () => void;
+  pickUp: () => boolean;
   cancelPointerInteraction: () => void;
   destroy(): void;
 };

package/dist/board/editor/editor.js

@@ -96,6 +96,11 @@ function createBoardEditor(options) {
 	ctx.snapshots = createSnapshotsModule(ctx);
 	ctx.remote = createRemoteModule(ctx);
 	const { document, query, camera, selection, creation, deletion, copy, interaction, animation, snapshots, remote } = ctx;
+	const transformChannels = options.touchRotation === false ? [
+		"scene",
+		"selection",
+		"hover"
+	] : ["scene", "selection"];
 	let viewStateQueued = false;
 	function emitViewState() {
 		viewStateQueued = false;
@@ -193,7 +198,7 @@ function createBoardEditor(options) {
 			return read(["scene", "selection"], selection.bounds);
 		},
 		get selectionTransform() {
-			return read(["scene", "selection"], selection.transform);
+			return read(transformChannels, selection.transform);
 		},
 		get camera() {
 			return read("camera", () => state.camera);
@@ -438,6 +443,8 @@ function createBoardEditor(options) {
 		pointerUp: interaction.pointerUp,
 		pointerLeave: interaction.pointerLeave,
 		subscribeTransforms: interaction.subscribeTransforms,
+		subscribeActivations: interaction.subscribeActivations,
+		pickUp: interaction.pickUp,
 		cancelPointerInteraction: interaction.cancel,
 		destroy() {
 			stopViewState();

package/dist/board/editor/index.d.ts

@@ -2,13 +2,13 @@ import { BOARD_CLIPBOARD_MIME } from "../../protocol/dist/board.js";
 import { AlignMode, DistributeAxis, alignFrames, distributeFrames, framesBounds } from "./align.js";
 import { BoardFocusOptions } from "./camera.js";
 import { BoardSelectionTransform, BoardTransformControl, resizeCursorForHandle, resolveSelectionTransform, selectionTransformControlAt } from "./selection-transform.js";
-import { BoardInteraction, BoardPointerEvent, BoardTransformEnd } from "./interaction.js";
+import { BoardActivation, BoardInteraction, BoardPointerEvent, BoardTransformEnd } from "./interaction.js";
 import { BoardAppMetadata, BoardTaskSource } from "./creation.js";
 import { BOARD_CLIPBOARD_VERSION, BoardClipboardPayload, DUPLICATE_OFFSET, MAX_CLIPBOARD_CHARS, MAX_CLIPBOARD_ITEMS, defaultPasteOffset, encodeClipboard, materializeClipboard, parseClipboard, remapItems } from "./clipboard.js";
 import { BoardNaturalSize } from "./snapshots.js";
 import { SnapAxis, SnapGuide, SnapOptions, SnapResult, computeSnap } from "./snapping.js";
 import { BoardEditorChannel, BoardEditorListener } from "./state.js";
-import { BOARD_HAND_TAP_SLOP, BoardToolId, canTapSelectWithHand, defaultBoardTool, isContinuousBoardTool, isCreationBoardTool, isWithinHandTapSlop } from "./tool.js";
+import { BOARD_HAND_TAP_SLOP, BOARD_MOUSE_TAP_SLOP, BOARD_TAP_MAX_MS, BoardToolId, boardTapSlop, canTapSelectWithHand, defaultBoardTool, isContinuousBoardTool, isCreationBoardTool, isWithinHandTapSlop } from "./tool.js";
 import { BoardCameraPolicy, BoardEditorOptions, BoardEditorPreferences, BoardPlayhead, BoardViewState } from "./context.js";
 import { CONNECTION_PORT_HIT_RADIUS, CONNECTION_PORT_OFFSET, CONNECTION_PORT_RADIUS, CONNECTION_PORT_TOUCH_HIT_RADIUS, CONNECTION_SIDES, ConnectionPort, connectionPortAt, connectionPorts, portHitRadius } from "./connection-ports.js";
 import { sameJson } from "../model/json.js";
@@ -16,4 +16,4 @@ import { BoardEditPlayhead, diffBoardEdits, isEmptyBoardPatch, readPath, routeBo
 import { BoardEditor, createBoardEditor } from "./editor.js";
 import { SpatialEntry, SpatialIndex, createSpatialIndex } from "./spatial.js";
 import { normalizeWheelDelta, wheelZoomFactor } from "./wheel.js";
-export { AlignMode, BOARD_CLIPBOARD_MIME, BOARD_CLIPBOARD_VERSION, BOARD_HAND_TAP_SLOP, type BoardAppMetadata, type BoardCameraPolicy, BoardClipboardPayload, BoardEditPlayhead, type BoardEditor, type BoardEditorChannel, type BoardEditorListener, type BoardEditorOptions, type BoardEditorPreferences, type BoardFocusOptions, type BoardInteraction, type BoardNaturalSize, type BoardPlayhead, type BoardPointerEvent, BoardSelectionTransform, type BoardTaskSource, BoardToolId, BoardTransformControl, type BoardTransformEnd, type BoardViewState, CONNECTION_PORT_HIT_RADIUS, CONNECTION_PORT_OFFSET, CONNECTION_PORT_RADIUS, CONNECTION_PORT_TOUCH_HIT_RADIUS, CONNECTION_SIDES, ConnectionPort, DUPLICATE_OFFSET, DistributeAxis, MAX_CLIPBOARD_CHARS, MAX_CLIPBOARD_ITEMS, SnapAxis, SnapGuide, SnapOptions, SnapResult, SpatialEntry, SpatialIndex, alignFrames, canTapSelectWithHand, computeSnap, connectionPortAt, connectionPorts, createBoardEditor, createSpatialIndex, defaultBoardTool, defaultPasteOffset, diffBoardEdits, distributeFrames, encodeClipboard, framesBounds, isContinuousBoardTool, isCreationBoardTool, isEmptyBoardPatch, isWithinHandTapSlop, materializeClipboard, normalizeWheelDelta, parseClipboard, portHitRadius, readPath, remapItems, resizeCursorForHandle, resolveSelectionTransform, routeBoardEdits, sameJson, selectionTransformControlAt, wheelZoomFactor, writePath };
+export { AlignMode, BOARD_CLIPBOARD_MIME, BOARD_CLIPBOARD_VERSION, BOARD_HAND_TAP_SLOP, BOARD_MOUSE_TAP_SLOP, BOARD_TAP_MAX_MS, type BoardActivation, type BoardAppMetadata, type BoardCameraPolicy, BoardClipboardPayload, BoardEditPlayhead, type BoardEditor, type BoardEditorChannel, type BoardEditorListener, type BoardEditorOptions, type BoardEditorPreferences, type BoardFocusOptions, type BoardInteraction, type BoardNaturalSize, type BoardPlayhead, type BoardPointerEvent, BoardSelectionTransform, type BoardTaskSource, BoardToolId, BoardTransformControl, type BoardTransformEnd, type BoardViewState, CONNECTION_PORT_HIT_RADIUS, CONNECTION_PORT_OFFSET, CONNECTION_PORT_RADIUS, CONNECTION_PORT_TOUCH_HIT_RADIUS, CONNECTION_SIDES, ConnectionPort, DUPLICATE_OFFSET, DistributeAxis, MAX_CLIPBOARD_CHARS, MAX_CLIPBOARD_ITEMS, SnapAxis, SnapGuide, SnapOptions, SnapResult, SpatialEntry, SpatialIndex, alignFrames, boardTapSlop, canTapSelectWithHand, computeSnap, connectionPortAt, connectionPorts, createBoardEditor, createSpatialIndex, defaultBoardTool, defaultPasteOffset, diffBoardEdits, distributeFrames, encodeClipboard, framesBounds, isContinuousBoardTool, isCreationBoardTool, isEmptyBoardPatch, isWithinHandTapSlop, materializeClipboard, normalizeWheelDelta, parseClipboard, portHitRadius, readPath, remapItems, resizeCursorForHandle, resolveSelectionTransform, routeBoardEdits, sameJson, selectionTransformControlAt, wheelZoomFactor, writePath };

package/dist/board/editor/index.js

@@ -5,9 +5,9 @@ import { diffBoardEdits, isEmptyBoardPatch, readPath, routeBoardEdits, writePath
 import { normalizeWheelDelta, wheelZoomFactor } from "./wheel.js";
 import { BOARD_CLIPBOARD_VERSION, DUPLICATE_OFFSET, MAX_CLIPBOARD_CHARS, MAX_CLIPBOARD_ITEMS, defaultPasteOffset, encodeClipboard, materializeClipboard, parseClipboard, remapItems } from "./clipboard.js";
 import { CONNECTION_PORT_HIT_RADIUS, CONNECTION_PORT_OFFSET, CONNECTION_PORT_RADIUS, CONNECTION_PORT_TOUCH_HIT_RADIUS, CONNECTION_SIDES, connectionPortAt, connectionPorts, portHitRadius } from "./connection-ports.js";
-import { BOARD_HAND_TAP_SLOP, canTapSelectWithHand, defaultBoardTool, isContinuousBoardTool, isCreationBoardTool, isWithinHandTapSlop } from "./tool.js";
+import { BOARD_HAND_TAP_SLOP, BOARD_MOUSE_TAP_SLOP, BOARD_TAP_MAX_MS, boardTapSlop, canTapSelectWithHand, defaultBoardTool, isContinuousBoardTool, isCreationBoardTool, isWithinHandTapSlop } from "./tool.js";
 import { resizeCursorForHandle, resolveSelectionTransform, selectionTransformControlAt } from "./selection-transform.js";
 import { computeSnap } from "./snapping.js";
 import { createSpatialIndex } from "./spatial.js";
 import { createBoardEditor } from "./editor.js";
-export { BOARD_CLIPBOARD_MIME, BOARD_CLIPBOARD_VERSION, BOARD_HAND_TAP_SLOP, CONNECTION_PORT_HIT_RADIUS, CONNECTION_PORT_OFFSET, CONNECTION_PORT_RADIUS, CONNECTION_PORT_TOUCH_HIT_RADIUS, CONNECTION_SIDES, DUPLICATE_OFFSET, MAX_CLIPBOARD_CHARS, MAX_CLIPBOARD_ITEMS, alignFrames, canTapSelectWithHand, computeSnap, connectionPortAt, connectionPorts, createBoardEditor, createSpatialIndex, defaultBoardTool, defaultPasteOffset, diffBoardEdits, distributeFrames, encodeClipboard, framesBounds, isContinuousBoardTool, isCreationBoardTool, isEmptyBoardPatch, isWithinHandTapSlop, materializeClipboard, normalizeWheelDelta, parseClipboard, portHitRadius, readPath, remapItems, resizeCursorForHandle, resolveSelectionTransform, routeBoardEdits, sameJson, selectionTransformControlAt, wheelZoomFactor, writePath };
+export { BOARD_CLIPBOARD_MIME, BOARD_CLIPBOARD_VERSION, BOARD_HAND_TAP_SLOP, BOARD_MOUSE_TAP_SLOP, BOARD_TAP_MAX_MS, CONNECTION_PORT_HIT_RADIUS, CONNECTION_PORT_OFFSET, CONNECTION_PORT_RADIUS, CONNECTION_PORT_TOUCH_HIT_RADIUS, CONNECTION_SIDES, DUPLICATE_OFFSET, MAX_CLIPBOARD_CHARS, MAX_CLIPBOARD_ITEMS, alignFrames, boardTapSlop, canTapSelectWithHand, computeSnap, connectionPortAt, connectionPorts, createBoardEditor, createSpatialIndex, defaultBoardTool, defaultPasteOffset, diffBoardEdits, distributeFrames, encodeClipboard, framesBounds, isContinuousBoardTool, isCreationBoardTool, isEmptyBoardPatch, isWithinHandTapSlop, materializeClipboard, normalizeWheelDelta, parseClipboard, portHitRadius, readPath, remapItems, resizeCursorForHandle, resolveSelectionTransform, routeBoardEdits, sameJson, selectionTransformControlAt, wheelZoomFactor, writePath };

package/dist/board/editor/interaction.d.ts

@@ -6,9 +6,19 @@ import "../model/index.js";
 import { BoardTransformControl } from "./selection-transform.js";
 import { EditorContext } from "./context.js";
 //#region src/board/editor/interaction.d.ts
+type BoardPress = {
+  type: "pressing";
+  itemId: string;
+  pointerId: number;
+  pointerType: string;
+  start: ScreenPoint;
+  world: WorldPoint;
+  camera: BoardViewport;
+  at: number;
+};
 type BoardInteraction = {
   type: "idle";
-} | {
+} | BoardPress | {
   type: "panning";
   start: ScreenPoint;
   origin: BoardViewport;
@@ -22,6 +32,10 @@ type BoardInteraction = {
   origin: Map<string, BoardFrame>;
   moved: boolean;
   duplicate: boolean;
+  tap?: {
+    itemId: string;
+    at: number;
+  };
 } | {
   type: "resizing";
   handle: ResizeHandle;
@@ -94,6 +108,11 @@ type BoardPointerEvent = {
   pressure: number;
   samples?: readonly BoardDrawInputSample[];
 };
+type BoardActivation = {
+  itemId: string;
+  pointerType: string;
+  selected: boolean;
+};
 type BoardTransformEnd = {
   ids: string[];
   operation: "move" | "resize" | "rotate" | "arrow";
@@ -117,9 +136,11 @@ declare function createInteractionModule(ctx: EditorContext): {
   pointerUp: (event: BoardPointerEvent) => void;
   pointerLeave: () => void;
   cancel: () => void;
+  pickUp: () => boolean;
   subscribeTransforms(listener: (event: BoardTransformEnd) => void): () => void;
+  subscribeActivations(listener: (event: BoardActivation) => void): () => void;
   destroy(): void;
 };
 type InteractionModule = ReturnType<typeof createInteractionModule>;
 //#endregion
-export { BoardInteraction, BoardPointerEvent, BoardTransformEnd, InteractionModule, createInteractionModule };
+export { BoardActivation, BoardInteraction, BoardPointerEvent, BoardTransformEnd, InteractionModule, createInteractionModule };

package/dist/board/editor/interaction.js

@@ -3,7 +3,7 @@ import { resolveSceneArrow } from "../model/arrow-geometry.js";
 import { appendBoardDrawSamples } from "../model/draw-input.js";
 import { createBoardItemId } from "../model/items/id.js";
 import { connectionPortAt, connectionPorts } from "./connection-ports.js";
-import { canTapSelectWithHand, isCreationBoardTool, isWithinHandTapSlop } from "./tool.js";
+import { boardTapSlop, canTapSelectWithHand, isCreationBoardTool, isWithinHandTapSlop } from "./tool.js";
 import { selectionTransformControlAt } from "./selection-transform.js";
 import { computeSnap } from "./snapping.js";
 import { memo } from "./state.js";
@@ -33,6 +33,15 @@ function createInteractionModule(ctx) {
 		for (const listener of transformListeners) listener(event);
 	}
 	const { state, options, registry } = ctx;
+	const activationListeners = /* @__PURE__ */ new Set();
+	function activate(itemId, at, pointerType, selected) {
+		if (performance.now() - at > 300 || !state.scene.get(itemId)) return;
+		for (const listener of activationListeners) listener({
+			itemId,
+			pointerType,
+			selected
+		});
+	}
 	const activePointers = /* @__PURE__ */ new Map();
 	let pinch = null;
 	const marquee = memo(() => [state.interaction], (interaction) => {
@@ -106,6 +115,7 @@ function createInteractionModule(ctx) {
 		if (!candidateId) return null;
 		const item = scene.get(candidateId);
 		if (!item || ctx.query.isLocked(item) || item.type === "arrow") return null;
+		if (!selection.includes(item.id) && registry.activation(item) === "tap") return null;
 		return registry.capabilities(item).canConnect ? item.id : null;
 	}
 	function visiblePorts() {
@@ -160,6 +170,71 @@ function createInteractionModule(ctx) {
 			size: arrow.size
 		};
 	}
+	function onSelectedItem(event) {
+		if (!canTapSelectWithHand(event.pointerType)) return false;
+		const item = ctx.query.itemAt(event.world);
+		return item !== null && state.selection.includes(item.id);
+	}
+	function plainPrimary(event) {
+		return event.button === 0 && !event.shiftKey && !event.metaKey && !event.ctrlKey && !event.altKey;
+	}
+	function press(event) {
+		if (!plainPrimary(event)) return false;
+		const item = ctx.query.itemAt(event.world);
+		if (!item || state.selection.includes(item.id) || registry.activation(item) !== "tap") return false;
+		state.interaction = {
+			type: "pressing",
+			itemId: item.id,
+			pointerId: event.pointerId,
+			pointerType: event.pointerType,
+			start: event.screen,
+			world: event.world,
+			camera: { ...state.camera },
+			at: performance.now()
+		};
+		return true;
+	}
+	function releasePress(gesture, event) {
+		const dx = event.screen.x - gesture.start.x;
+		const dy = event.screen.y - gesture.start.y;
+		if (Math.hypot(dx, dy) <= boardTapSlop(gesture.pointerType)) return;
+		const item = state.scene.get(gesture.itemId);
+		if (!(!options.readonly && state.tool === "select" && item && !ctx.query.isLocked(item) && registry.capabilities(item).canMove)) {
+			state.interaction = {
+				type: "panning",
+				start: gesture.start,
+				origin: gesture.camera,
+				moved: true,
+				tapSelection: null
+			};
+			ctx.camera.setCamera(panBy(gesture.camera, dx, dy));
+			return;
+		}
+		const translating = {
+			type: "translating",
+			start: gesture.world,
+			origin: ctx.selection.framesFor([gesture.itemId]),
+			moved: false,
+			duplicate: false
+		};
+		state.interaction = translating;
+		translate(translating, event);
+	}
+	function pickUp() {
+		const gesture = state.interaction;
+		if (options.readonly || gesture.type !== "pressing") return false;
+		const item = state.scene.get(gesture.itemId);
+		if (!item || ctx.query.isLocked(item) || !registry.capabilities(item).canMove) return false;
+		state.selection = [item.id];
+		state.interaction = {
+			type: "translating",
+			start: state.hoverPoint ?? gesture.world,
+			origin: ctx.selection.framesFor([item.id]),
+			moved: false,
+			duplicate: false
+		};
+		return true;
+	}
 	function pointerDown(event) {
 		ctx.camera.cancelAnimation();
 		state.hoverPoint = event.world;
@@ -173,6 +248,7 @@ function createInteractionModule(ctx) {
 		}
 		if (activePointers.size > 2) return;
 		const additive = event.shiftKey || event.metaKey || event.ctrlKey;
+		if (!spaceHeld && (tool === "hand" || options.readonly) && press(event)) return;
 		if (tool === "hand" || spaceHeld || event.button === 1) {
 			const tapSelection = tool === "hand" && !spaceHeld && event.button !== 1 && canTapSelectWithHand(event.pointerType) ? { targetId: ctx.query.itemAt(event.world)?.id ?? null } : null;
 			state.interaction = {
@@ -225,7 +301,7 @@ function createInteractionModule(ctx) {
 				ctx.creation.beginTextDraft(event.world);
 				return;
 		}
-		const port = connectionPortAt$1(event.world, event.pointerType);
+		const port = onSelectedItem(event) ? null : connectionPortAt$1(event.world, event.pointerType);
 		if (port) {
 			state.interaction = arrowGesture(port.point, event.world, port.itemId, port.side);
 			return;
@@ -278,17 +354,23 @@ function createInteractionModule(ctx) {
 			};
 			return;
 		}
+		if (press(event)) return;
 		const item = ctx.query.itemAt(event.world);
 		if (!item) return brush(event, additive);
 		if (additive) ctx.selection.toggle(item.id);
 		else if (!state.selection.includes(item.id)) state.selection = [item.id];
 		const movable = ctx.selection.movable();
+		const tap = plainPrimary(event) && state.selection.length === 1 && registry.activation(item) === "tap" ? {
+			itemId: item.id,
+			at: performance.now()
+		} : void 0;
 		state.interaction = movable.length === 0 ? { type: "idle" } : {
 			type: "translating",
 			start: event.world,
 			origin: ctx.selection.framesFor(movable),
 			moved: false,
-			duplicate: event.altKey
+			duplicate: event.altKey,
+			...tap ? { tap } : {}
 		};
 	}
 	function pinchMove() {
@@ -472,6 +554,7 @@ function createInteractionModule(ctx) {
 				ctx.camera.setCamera(panBy(interaction.origin, dx, dy));
 				return;
 			}
+			case "pressing": return releasePress(interaction, event);
 			case "translating": return translate(interaction, event);
 			case "resizing": return resize(interaction, event);
 			case "rotating": return rotate(interaction, event);
@@ -532,11 +615,14 @@ function createInteractionModule(ctx) {
 					state.selection = targetId && state.scene.get(targetId) ? [targetId] : [];
 				}
 				break;
+			case "pressing":
+				activate(gesture.itemId, gesture.at, gesture.pointerType, false);
+				break;
 			case "translating":
 				if (gesture.moved) {
-					for (const [id, item] of reparentDropped(ctx.query.rootsOf(state.selection))) ctx.document.setDraftItem(id, item);
+					for (const [id, item] of reparentDropped([...gesture.origin.keys()])) ctx.document.setDraftItem(id, item);
 					ctx.document.commit();
-				}
+				} else if (gesture.tap) activate(gesture.tap.itemId, gesture.tap.at, event.pointerType, true);
 				break;
 			case "resizing":
 			case "rotating":
@@ -610,15 +696,23 @@ function createInteractionModule(ctx) {
 		pointerUp,
 		pointerLeave,
 		cancel,
+		pickUp,
 		subscribeTransforms(listener) {
 			transformListeners.add(listener);
 			return () => {
 				transformListeners.delete(listener);
 			};
 		},
+		subscribeActivations(listener) {
+			activationListeners.add(listener);
+			return () => {
+				activationListeners.delete(listener);
+			};
+		},
 		destroy() {
 			activePointers.clear();
 			transformListeners.clear();
+			activationListeners.clear();
 		}
 	};
 }

package/dist/board/editor/query.d.ts

@@ -18,7 +18,7 @@ declare function createQueryModule(ctx: EditorContext): {
   idsInRect: (rect: Rect, includeTemporary?: boolean) => string[];
   frameAt: (point: WorldPoint, exclude?: ReadonlySet<string>) => BoardSceneItem | null;
   itemAt: (point: WorldPoint, exclude?: ReadonlySet<string>, includeTemporary?: boolean) => BoardSceneItem | null;
-  labelItemAt: (point: WorldPoint) => BoardSceneItem | null;
+  labelItemAt: (point: WorldPoint, frameLabelSize?: number) => BoardSceneItem | null;
   arrowHandleAt: (point: WorldPoint) => "start" | "end" | "mid" | null;
   connectTargetAt: (point: WorldPoint, exclude?: ReadonlySet<string>) => string | null;
 };

package/dist/board/editor/query.js

@@ -1,6 +1,7 @@
 import { parseBoardMediaSource } from "../../protocol/dist/board-model.js";
 import { rectContainsPoint, unionRects } from "../model/geometry.js";
 import { arrowHitRadius, arrowPathBounds, distanceToArrow, resolveSceneArrow } from "../model/arrow-geometry.js";
+import { frameLabelHitRect } from "../model/text-metrics.js";
 import { createSpatialIndex } from "./spatial.js";
 //#region src/board/editor/query.ts
 const NO_IDS = /* @__PURE__ */ new Set();
@@ -139,7 +140,7 @@ function createQueryModule(ctx) {
 		}
 		return null;
 	}
-	function labelItemAt(point) {
+	function labelItemAt(point, frameLabelSize = 12) {
 		ensureSpatial();
 		const { scene, selection, camera } = state;
 		const nearby = spatial.idsAtPoint(point);
@@ -147,12 +148,7 @@ function createQueryModule(ctx) {
 		for (const id of new Set(candidates)) {
 			const item = scene.get(id);
 			if (!item || !state.base.items[id] || isLocked(item)) continue;
-			if (item.type === "frame" && rectContainsPoint({
-				x: item.frame.x,
-				y: item.frame.y - 22,
-				width: Math.max(48, item.frame.width * .5),
-				height: 24
-			}, point)) return item;
+			if (item.type === "frame" && rectContainsPoint(frameLabelHitRect(item.frame, frameLabelSize), point)) return item;
 			if (item.type === "arrow") {
 				const resolved = resolveSceneArrow(item, scene);
 				const radius = Math.max(10, (item.props.fontSize ?? 14) * .9) / Math.min(1, camera.zoom);

package/dist/board/editor/selection.js

@@ -1,6 +1,7 @@
 import { selectionBounds } from "../model/geometry.js";
 import { sceneItemToItem } from "../model/scene.js";
 import { alignFrames, distributeFrames } from "./align.js";
+import { canTapSelectWithHand } from "./tool.js";
 import { resolveSelectionTransform } from "./selection-transform.js";
 import { memo } from "./state.js";
 //#region src/board/editor/selection.ts
@@ -17,7 +18,18 @@ function createSelectionModule(ctx) {
 		return result;
 	});
 	const bounds = memo(() => [items()], (selected) => selectionBounds(selected.map((item) => item.frame)));
-	const transform = memo(() => [items(), bounds()], (selected, rect) => resolveSelectionTransform(registry, selected, rect));
+	const rotatesOnTouch = ctx.options.touchRotation !== false;
+	const transform = memo(() => [
+		items(),
+		bounds(),
+		rotatesOnTouch || !canTapSelectWithHand(state.hoverPointerType)
+	], (selected, rect, rotates) => {
+		const resolved = resolveSelectionTransform(registry, selected, rect);
+		return resolved && !rotates ? {
+			...resolved,
+			canRotate: false
+		} : resolved;
+	});
 	function set(ids) {
 		state.selection = ids.filter((id) => Boolean(state.base.items[id]));
 	}

package/dist/board/editor/tool.d.ts

@@ -1,10 +1,13 @@
 //#region src/board/editor/tool.d.ts
 type BoardToolId = "select" | "hand" | "text" | "shape" | "draw" | "arrow" | "frame";
 declare const BOARD_HAND_TAP_SLOP = 8;
+declare const BOARD_MOUSE_TAP_SLOP = 4;
+declare const BOARD_TAP_MAX_MS = 300;
+declare function boardTapSlop(pointerType: string): number;
 declare function defaultBoardTool(isMobile: boolean): BoardToolId;
 declare function canTapSelectWithHand(pointerType: string): boolean;
 declare function isWithinHandTapSlop(dx: number, dy: number): boolean;
 declare function isContinuousBoardTool(tool: BoardToolId): boolean;
 declare function isCreationBoardTool(tool: BoardToolId): boolean;
 //#endregion
-export { BOARD_HAND_TAP_SLOP, BoardToolId, canTapSelectWithHand, defaultBoardTool, isContinuousBoardTool, isCreationBoardTool, isWithinHandTapSlop };
+export { BOARD_HAND_TAP_SLOP, BOARD_MOUSE_TAP_SLOP, BOARD_TAP_MAX_MS, BoardToolId, boardTapSlop, canTapSelectWithHand, defaultBoardTool, isContinuousBoardTool, isCreationBoardTool, isWithinHandTapSlop };

package/dist/board/editor/tool.js

@@ -1,5 +1,10 @@
 //#region src/board/editor/tool.ts
 const BOARD_HAND_TAP_SLOP = 8;
+const BOARD_MOUSE_TAP_SLOP = 4;
+const BOARD_TAP_MAX_MS = 300;
+function boardTapSlop(pointerType) {
+	return pointerType === "mouse" ? 4 : 8;
+}
 function defaultBoardTool(isMobile) {
 	return isMobile ? "hand" : "select";
 }
@@ -16,4 +21,4 @@ function isCreationBoardTool(tool) {
 	return tool === "text" || tool === "shape" || tool === "draw" || tool === "arrow" || tool === "frame";
 }
 //#endregion
-export { BOARD_HAND_TAP_SLOP, canTapSelectWithHand, defaultBoardTool, isContinuousBoardTool, isCreationBoardTool, isWithinHandTapSlop };
+export { BOARD_HAND_TAP_SLOP, BOARD_MOUSE_TAP_SLOP, BOARD_TAP_MAX_MS, boardTapSlop, canTapSelectWithHand, defaultBoardTool, isContinuousBoardTool, isCreationBoardTool, isWithinHandTapSlop };

package/dist/board/model/asset-key.d.ts

@@ -5,7 +5,15 @@ type BoardAssetKeySource = {
   kind: "file" | "url";
   media: BoardAssetMedia;
   value: string;
+  fit?: "cover";
 };
+/** `src` is a Space file path or a URL; `fit: "cover"` sizes an image by its short edge. */
+type BoardAssetRef = {
+  src: string;
+  media?: "image" | "video";
+  fit?: "contain" | "cover";
+};
+declare function boardAssetRefKey({ src, media, fit }: BoardAssetRef): string | null;
 declare function imageAssetKey(item: BoardSceneItem): string | null;
 declare function boardAssetKey(item: BoardSceneItem): string | null;
 declare function boardAssetKeySource(key: string): BoardAssetKeySource | null;
@@ -13,4 +21,4 @@ declare function boardTexturePixels(item: BoardSceneItem, scale: number): number
 declare const BOARD_THUMBNAIL_EDGE = 64;
 declare function boardTextureEdge(item: BoardSceneItem, scale: number): number;
 //#endregion
-export { BOARD_THUMBNAIL_EDGE, BoardAssetKeySource, BoardAssetMedia, boardAssetKey, boardAssetKeySource, boardTextureEdge, boardTexturePixels, imageAssetKey };
+export { BOARD_THUMBNAIL_EDGE, BoardAssetKeySource, BoardAssetMedia, BoardAssetRef, boardAssetKey, boardAssetKeySource, boardAssetRefKey, boardTextureEdge, boardTexturePixels, imageAssetKey };