@ai-matrx/canvas 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as CanvasItemId, a as CanvasWindowId, b as CanvasJson, c as CanvasLayoutNode, d as CanvasPaneId, e as CanvasStoreBinding, f as CanvasState, g as CanvasAction, h as CanvasController, i as CanvasItem, j as CanvasExtraWindow, k as CanvasPane, l as canvasWindowOfItem } from './toggleKind-A9v45oSb.cjs';
-export { m as CANVAS_DEFAULT_KEY, n as CANVAS_DEFAULT_WIDTH, o as CANVAS_DESKTOP_LAYOUT_RULES, p as CANVAS_MAIN_WINDOW, q as CANVAS_MIN_SPLIT_FRACTION, r as CANVAS_MIN_WIDTH, s as CANVAS_STORAGE_KEY, t as CANVAS_WEB_LAYOUT_RULES, u as CanvasControllerOptions, v as CanvasErrorReport, w as CanvasErrorSink, x as CanvasKeyValueStore, y as CanvasKindVisibility, z as CanvasLayoutRules, A as CanvasOpenInput, B as CanvasOpenTarget, D as CanvasOrientation, E as CanvasPersistencePort, F as CanvasRect, G as CanvasSessionAttachReason, H as CanvasSessionDetachReason, I as CanvasSessionEvent, J as CanvasSessionHooks, K as CanvasSplitId, L as CanvasWindowCloseMode, M as CanvasWindowFrame, N as CanvasWindowPorts, R as ReduxStoreLike, T as ToggleKindInput, O as bindCanvasToReduxStore, P as canvasActions, Q as canvasReducer, S as canvasWindowFrame, U as canvasWindowOfPane, V as clampDraggedCanvasWidth, W as consoleCanvasErrorSink, X as createCanvasController, Y as createCanvasStore, Z as createInitialCanvasState, _ as createKeyValueCanvasPersistence, $ as createLocalStorageCanvasPersistence, a0 as defaultCanvasWidth, a1 as fitCanvasWidth, a2 as foldCanvasWindows, a3 as isCanvasAction, a4 as listCanvasWindowIds, a5 as resolveCanvasLayoutRules, a6 as sanitizeCanvasSnapshot, a7 as selectCanvasKindVisibility, a8 as shouldStackSplit, a9 as toPersistableSnapshot, aa as toggleKind } from './toggleKind-A9v45oSb.cjs';
+import { C as CanvasItemId, a as CanvasWindowId, b as CanvasJson, c as CanvasLayoutNode, d as CanvasPaneId, e as CanvasStoreBinding, f as CanvasState, g as CanvasAction, h as CanvasController, i as CanvasItem, j as CanvasExtraWindow, k as CanvasHistoryEntry, l as CanvasPane, m as canvasWindowOfItem } from './toggleKind-BD78LnMB.cjs';
+export { n as CANVAS_DEFAULT_KEY, o as CANVAS_DEFAULT_WIDTH, p as CANVAS_DESKTOP_LAYOUT_RULES, q as CANVAS_HISTORY_LIMIT, r as CANVAS_LAUNCHER_KIND, s as CANVAS_MAIN_WINDOW, t as CANVAS_MIN_SPLIT_FRACTION, u as CANVAS_MIN_WIDTH, v as CANVAS_NARROW_WIDTH, w as CANVAS_STORAGE_KEY, x as CANVAS_WEB_LAYOUT_RULES, y as CanvasControllerOptions, z as CanvasErrorReport, A as CanvasErrorSink, B as CanvasKeyValueStore, D as CanvasKindVisibility, E as CanvasLayoutRules, F as CanvasNavigateInput, G as CanvasOpenInput, H as CanvasOpenTarget, I as CanvasOrientation, J as CanvasPersistencePort, K as CanvasPreferredTarget, L as CanvasPresentation, M as CanvasPresentationOrientation, N as CanvasRect, O as CanvasSessionAttachReason, P as CanvasSessionDetachReason, Q as CanvasSessionEvent, R as CanvasSessionHooks, S as CanvasSplitId, T as CanvasWindowCloseMode, U as CanvasWindowFrame, V as CanvasWindowPorts, W as ReduxStoreLike, X as ToggleKindInput, Y as bindCanvasToReduxStore, Z as canvasActions, _ as canvasOrientation, $ as canvasPresentation, a0 as canvasReducer, a1 as canvasWindowFrame, a2 as canvasWindowOfPane, a3 as clampDraggedCanvasWidth, a4 as consoleCanvasErrorSink, a5 as createCanvasController, a6 as createCanvasStore, a7 as createInitialCanvasState, a8 as createKeyValueCanvasPersistence, a9 as createLocalStorageCanvasPersistence, aa as defaultCanvasWidth, ab as fitCanvasWidth, ac as foldCanvasWindows, ad as isCanvasAction, ae as listCanvasWindowIds, af as preferredFlowDirection, ag as resolveCanvasLayoutRules, ah as sanitizeCanvasSnapshot, ai as selectCanvasKindVisibility, aj as shouldStackSplit, ak as toPersistableSnapshot, al as toggleKind } from './toggleKind-BD78LnMB.cjs';
 
 declare function canvasItemId(kind: string, key: string): CanvasItemId;
 declare function parseCanvasItemId(id: CanvasItemId): {
@@ -142,5 +142,9 @@ declare function selectCanvasWindows(s: CanvasState): CanvasState["windows"];
 declare const selectCanvasExtraWindow: (s: CanvasState, windowId: CanvasWindowId) => CanvasExtraWindow | undefined;
 /** The window an item is in, or null when it is not on the canvas. */
 declare const selectCanvasWindowOfItem: typeof canvasWindowOfItem;
+/** What a tab showed before, oldest first. Stable per state. */
+declare function selectCanvasItemHistory(s: CanvasState, itemId: CanvasItemId): readonly CanvasHistoryEntry[];
+/** Whether a tab offers Back (it navigated in place). */
+declare const selectCanvasCanGoBack: (s: CanvasState, itemId: CanvasItemId) => boolean;
 
-export { CANVAS_SHORTCUTS, CanvasAction, type CanvasCommandId, CanvasController, CanvasExtraWindow, CanvasItem, CanvasItemId, CanvasJson, type CanvasKeyInput, CanvasLayoutNode, CanvasPane, CanvasPaneId, type CanvasShortcut, type CanvasShortcutWhen, CanvasState, CanvasStoreBinding, CanvasWindowId, type RemoteCanvasStore, type RemoteCanvasStoreOptions, canvasItemId, canvasShortcutHint, canvasWindowId, canvasWindowOfItem, createRemoteCanvasStore, findNonJson, isCanvasJson, listPaneIds, matchesCanvasAccelerator, normalizeSizes, parseCanvasItemId, runCanvasCommand, selectCanvasActiveItem, selectCanvasExtraWindow, selectCanvasFocusedPaneId, selectCanvasIsFullscreen, selectCanvasIsHydrated, selectCanvasIsOpen, selectCanvasItem, selectCanvasItemCount, selectCanvasLayout, selectCanvasPane, selectCanvasPaneCount, selectCanvasWidth, selectCanvasWindowItemCount, selectCanvasWindowOfItem, selectCanvasWindows, shareStructure };
+export { CANVAS_SHORTCUTS, CanvasAction, type CanvasCommandId, CanvasController, CanvasExtraWindow, CanvasHistoryEntry, CanvasItem, CanvasItemId, CanvasJson, type CanvasKeyInput, CanvasLayoutNode, CanvasPane, CanvasPaneId, type CanvasShortcut, type CanvasShortcutWhen, CanvasState, CanvasStoreBinding, CanvasWindowId, type RemoteCanvasStore, type RemoteCanvasStoreOptions, canvasItemId, canvasShortcutHint, canvasWindowId, canvasWindowOfItem, createRemoteCanvasStore, findNonJson, isCanvasJson, listPaneIds, matchesCanvasAccelerator, normalizeSizes, parseCanvasItemId, runCanvasCommand, selectCanvasActiveItem, selectCanvasCanGoBack, selectCanvasExtraWindow, selectCanvasFocusedPaneId, selectCanvasIsFullscreen, selectCanvasIsHydrated, selectCanvasIsOpen, selectCanvasItem, selectCanvasItemCount, selectCanvasItemHistory, selectCanvasLayout, selectCanvasPane, selectCanvasPaneCount, selectCanvasWidth, selectCanvasWindowItemCount, selectCanvasWindowOfItem, selectCanvasWindows, shareStructure };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as CanvasItemId, a as CanvasWindowId, b as CanvasJson, c as CanvasLayoutNode, d as CanvasPaneId, e as CanvasStoreBinding, f as CanvasState, g as CanvasAction, h as CanvasController, i as CanvasItem, j as CanvasExtraWindow, k as CanvasPane, l as canvasWindowOfItem } from './toggleKind-A9v45oSb.js';
-export { m as CANVAS_DEFAULT_KEY, n as CANVAS_DEFAULT_WIDTH, o as CANVAS_DESKTOP_LAYOUT_RULES, p as CANVAS_MAIN_WINDOW, q as CANVAS_MIN_SPLIT_FRACTION, r as CANVAS_MIN_WIDTH, s as CANVAS_STORAGE_KEY, t as CANVAS_WEB_LAYOUT_RULES, u as CanvasControllerOptions, v as CanvasErrorReport, w as CanvasErrorSink, x as CanvasKeyValueStore, y as CanvasKindVisibility, z as CanvasLayoutRules, A as CanvasOpenInput, B as CanvasOpenTarget, D as CanvasOrientation, E as CanvasPersistencePort, F as CanvasRect, G as CanvasSessionAttachReason, H as CanvasSessionDetachReason, I as CanvasSessionEvent, J as CanvasSessionHooks, K as CanvasSplitId, L as CanvasWindowCloseMode, M as CanvasWindowFrame, N as CanvasWindowPorts, R as ReduxStoreLike, T as ToggleKindInput, O as bindCanvasToReduxStore, P as canvasActions, Q as canvasReducer, S as canvasWindowFrame, U as canvasWindowOfPane, V as clampDraggedCanvasWidth, W as consoleCanvasErrorSink, X as createCanvasController, Y as createCanvasStore, Z as createInitialCanvasState, _ as createKeyValueCanvasPersistence, $ as createLocalStorageCanvasPersistence, a0 as defaultCanvasWidth, a1 as fitCanvasWidth, a2 as foldCanvasWindows, a3 as isCanvasAction, a4 as listCanvasWindowIds, a5 as resolveCanvasLayoutRules, a6 as sanitizeCanvasSnapshot, a7 as selectCanvasKindVisibility, a8 as shouldStackSplit, a9 as toPersistableSnapshot, aa as toggleKind } from './toggleKind-A9v45oSb.js';
+import { C as CanvasItemId, a as CanvasWindowId, b as CanvasJson, c as CanvasLayoutNode, d as CanvasPaneId, e as CanvasStoreBinding, f as CanvasState, g as CanvasAction, h as CanvasController, i as CanvasItem, j as CanvasExtraWindow, k as CanvasHistoryEntry, l as CanvasPane, m as canvasWindowOfItem } from './toggleKind-BD78LnMB.js';
+export { n as CANVAS_DEFAULT_KEY, o as CANVAS_DEFAULT_WIDTH, p as CANVAS_DESKTOP_LAYOUT_RULES, q as CANVAS_HISTORY_LIMIT, r as CANVAS_LAUNCHER_KIND, s as CANVAS_MAIN_WINDOW, t as CANVAS_MIN_SPLIT_FRACTION, u as CANVAS_MIN_WIDTH, v as CANVAS_NARROW_WIDTH, w as CANVAS_STORAGE_KEY, x as CANVAS_WEB_LAYOUT_RULES, y as CanvasControllerOptions, z as CanvasErrorReport, A as CanvasErrorSink, B as CanvasKeyValueStore, D as CanvasKindVisibility, E as CanvasLayoutRules, F as CanvasNavigateInput, G as CanvasOpenInput, H as CanvasOpenTarget, I as CanvasOrientation, J as CanvasPersistencePort, K as CanvasPreferredTarget, L as CanvasPresentation, M as CanvasPresentationOrientation, N as CanvasRect, O as CanvasSessionAttachReason, P as CanvasSessionDetachReason, Q as CanvasSessionEvent, R as CanvasSessionHooks, S as CanvasSplitId, T as CanvasWindowCloseMode, U as CanvasWindowFrame, V as CanvasWindowPorts, W as ReduxStoreLike, X as ToggleKindInput, Y as bindCanvasToReduxStore, Z as canvasActions, _ as canvasOrientation, $ as canvasPresentation, a0 as canvasReducer, a1 as canvasWindowFrame, a2 as canvasWindowOfPane, a3 as clampDraggedCanvasWidth, a4 as consoleCanvasErrorSink, a5 as createCanvasController, a6 as createCanvasStore, a7 as createInitialCanvasState, a8 as createKeyValueCanvasPersistence, a9 as createLocalStorageCanvasPersistence, aa as defaultCanvasWidth, ab as fitCanvasWidth, ac as foldCanvasWindows, ad as isCanvasAction, ae as listCanvasWindowIds, af as preferredFlowDirection, ag as resolveCanvasLayoutRules, ah as sanitizeCanvasSnapshot, ai as selectCanvasKindVisibility, aj as shouldStackSplit, ak as toPersistableSnapshot, al as toggleKind } from './toggleKind-BD78LnMB.js';
 
 declare function canvasItemId(kind: string, key: string): CanvasItemId;
 declare function parseCanvasItemId(id: CanvasItemId): {
@@ -142,5 +142,9 @@ declare function selectCanvasWindows(s: CanvasState): CanvasState["windows"];
 declare const selectCanvasExtraWindow: (s: CanvasState, windowId: CanvasWindowId) => CanvasExtraWindow | undefined;
 /** The window an item is in, or null when it is not on the canvas. */
 declare const selectCanvasWindowOfItem: typeof canvasWindowOfItem;
+/** What a tab showed before, oldest first. Stable per state. */
+declare function selectCanvasItemHistory(s: CanvasState, itemId: CanvasItemId): readonly CanvasHistoryEntry[];
+/** Whether a tab offers Back (it navigated in place). */
+declare const selectCanvasCanGoBack: (s: CanvasState, itemId: CanvasItemId) => boolean;
 
-export { CANVAS_SHORTCUTS, CanvasAction, type CanvasCommandId, CanvasController, CanvasExtraWindow, CanvasItem, CanvasItemId, CanvasJson, type CanvasKeyInput, CanvasLayoutNode, CanvasPane, CanvasPaneId, type CanvasShortcut, type CanvasShortcutWhen, CanvasState, CanvasStoreBinding, CanvasWindowId, type RemoteCanvasStore, type RemoteCanvasStoreOptions, canvasItemId, canvasShortcutHint, canvasWindowId, canvasWindowOfItem, createRemoteCanvasStore, findNonJson, isCanvasJson, listPaneIds, matchesCanvasAccelerator, normalizeSizes, parseCanvasItemId, runCanvasCommand, selectCanvasActiveItem, selectCanvasExtraWindow, selectCanvasFocusedPaneId, selectCanvasIsFullscreen, selectCanvasIsHydrated, selectCanvasIsOpen, selectCanvasItem, selectCanvasItemCount, selectCanvasLayout, selectCanvasPane, selectCanvasPaneCount, selectCanvasWidth, selectCanvasWindowItemCount, selectCanvasWindowOfItem, selectCanvasWindows, shareStructure };
+export { CANVAS_SHORTCUTS, CanvasAction, type CanvasCommandId, CanvasController, CanvasExtraWindow, CanvasHistoryEntry, CanvasItem, CanvasItemId, CanvasJson, type CanvasKeyInput, CanvasLayoutNode, CanvasPane, CanvasPaneId, type CanvasShortcut, type CanvasShortcutWhen, CanvasState, CanvasStoreBinding, CanvasWindowId, type RemoteCanvasStore, type RemoteCanvasStoreOptions, canvasItemId, canvasShortcutHint, canvasWindowId, canvasWindowOfItem, createRemoteCanvasStore, findNonJson, isCanvasJson, listPaneIds, matchesCanvasAccelerator, normalizeSizes, parseCanvasItemId, runCanvasCommand, selectCanvasActiveItem, selectCanvasCanGoBack, selectCanvasExtraWindow, selectCanvasFocusedPaneId, selectCanvasIsFullscreen, selectCanvasIsHydrated, selectCanvasIsOpen, selectCanvasItem, selectCanvasItemCount, selectCanvasItemHistory, selectCanvasLayout, selectCanvasPane, selectCanvasPaneCount, selectCanvasWidth, selectCanvasWindowItemCount, selectCanvasWindowOfItem, selectCanvasWindows, shareStructure };

package/dist/index.js

@@ -1,5 +1,7 @@
 // src/core/types.ts
 var CANVAS_MAIN_WINDOW = "main";
+var CANVAS_LAUNCHER_KIND = "canvas.launcher";
+var CANVAS_HISTORY_LIMIT = 50;
 var CANVAS_MIN_WIDTH = 360;
 var CANVAS_DEFAULT_WIDTH = 640;
 var CANVAS_MIN_SPLIT_FRACTION = 0.12;
@@ -165,6 +167,10 @@ var canvasActions = {
   }),
   /** Gives an item a new identity in place (e.g. a draft that was just saved and now has an id). */
   rekey: (itemId, key) => ({ type: `${P}rekey`, payload: { itemId, key } }),
+  /** Replaces a tab's content with another item in place, remembering what it showed (Back returns). */
+  navigate: (itemId, to) => ({ type: `${P}navigate`, payload: { itemId, to, now: Date.now() } }),
+  /** Returns a tab to what it showed before its last navigate. */
+  back: (itemId) => ({ type: `${P}back`, payload: { itemId, now: Date.now() } }),
   closeItem: (itemId) => ({ type: `${P}closeItem`, payload: { itemId } }),
   closeOthers: (itemId) => ({ type: `${P}closeOthers`, payload: { itemId } }),
   activate: (itemId) => ({ type: `${P}activate`, payload: { itemId } }),
@@ -361,6 +367,63 @@ function sendHome(state, itemId, home, activate) {
   next = insertInto(next, homeFrame.focusedPaneId, itemId, activate);
   return activate ? withFrame(next, target, { focusedPaneId: homeFrame.focusedPaneId }) : next;
 }
+function newItem(kind, key, title, data, now, history) {
+  const id = canvasItemId(kind, key);
+  return {
+    id,
+    kind,
+    key,
+    title,
+    data,
+    openedAt: now,
+    updatedAt: now,
+    instance: `${now.toString(36)}:${id}`,
+    ...history && history.length > 0 ? { history: history.slice(-CANVAS_HISTORY_LIMIT) } : {}
+  };
+}
+function historyEntry(item) {
+  return { kind: item.kind, key: item.key, title: item.title, data: item.data };
+}
+function replaceInPlace(state, current, next) {
+  const pane = paneOf(state, current.id);
+  if (!pane) return state;
+  const items = { ...state.items, [next.id]: next };
+  delete items[current.id];
+  const withItems = { ...state, items };
+  const replaced = withPane(withItems, {
+    ...pane,
+    itemIds: pane.itemIds.map((id) => id === current.id ? next.id : id),
+    activeItemId: pane.activeItemId === current.id ? next.id : pane.activeItemId
+  });
+  return focus(replaced, pane.id);
+}
+function focusExisting(state, itemId) {
+  const pane = paneOf(state, itemId);
+  if (!pane) return state;
+  const next = focus(withPane(state, { ...pane, activeItemId: itemId }), pane.id);
+  const windowId = canvasWindowOfPane(next, pane.id);
+  return windowId ? withFrame(next, windowId, { isOpen: true }) : next;
+}
+function sanitizeHistory(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const e = entry;
+    if (typeof e.kind !== "string" || typeof e.key !== "string") continue;
+    out.push({ kind: e.kind, key: e.key, title: typeof e.title === "string" ? e.title : null, data: e.data ?? null });
+  }
+  return out.slice(-CANVAS_HISTORY_LIMIT);
+}
+function sanitizeItem(item) {
+  const history = sanitizeHistory(item.history);
+  const { history: _history, instance, ...rest } = item;
+  return {
+    ...rest,
+    ...typeof instance === "string" && instance ? { instance } : {},
+    ...history.length > 0 ? { history } : {}
+  };
+}
 function clampWidth(width) {
   return Number.isFinite(width) ? Math.max(CANVAS_MIN_WIDTH, Math.round(width)) : null;
 }
@@ -408,7 +471,7 @@ function sanitizeCanvasSnapshot(raw) {
   const items = {};
   for (const [id, item] of Object.entries(s.items)) {
     if (item && typeof item.kind === "string" && typeof item.key === "string" && canvasItemId(item.kind, item.key) === id) {
-      items[id] = item;
+      items[id] = sanitizeItem(item);
     }
   }
   const placed = /* @__PURE__ */ new Set();
@@ -482,7 +545,7 @@ function canvasReducer(state = createInitialCanvasState(), action) {
           next = insertInto(next, frame2.focusedPaneId, itemId, true);
         }
       } else {
-        const item = { id: itemId, kind, key, title: title ?? null, data: data ?? null, openedAt: now, updatedAt: now };
+        const item = newItem(kind, key, title ?? null, data ?? null, now);
         next = ensureWindow({ ...next, items: { ...next.items, [itemId]: item } }, revealIn);
         const frame2 = canvasWindowFrame(next, revealIn) ?? next;
         let paneId = frame2.focusedPaneId;
@@ -531,6 +594,35 @@ function canvasReducer(state = createInitialCanvasState(), action) {
       }
       return { ...state, items, panes };
     }
+    case `${P}navigate`: {
+      const { itemId, to, now } = action.payload;
+      const current = state.items[itemId];
+      if (!current || !paneOf(state, itemId)) return state;
+      const targetId = canvasItemId(to.kind, to.key);
+      if (targetId === itemId) {
+        const refresh = { type: `${P}update`, payload: { itemId, data: to.data, title: to.title, now } };
+        return canvasReducer(state, refresh);
+      }
+      if (state.items[targetId]) {
+        const focused = focusExisting(state, targetId);
+        return current.kind === CANVAS_LAUNCHER_KIND ? canvasReducer(focused, canvasActions.closeItem(itemId)) : focused;
+      }
+      const history = [...current.history ?? [], historyEntry(current)];
+      return replaceInPlace(state, current, newItem(to.kind, to.key, to.title ?? null, to.data ?? null, now, history));
+    }
+    case `${P}back`: {
+      const { itemId, now } = action.payload;
+      const current = state.items[itemId];
+      const history = current?.history ?? [];
+      const entry = history[history.length - 1];
+      if (!current || !entry || !paneOf(state, itemId)) return state;
+      const targetId = canvasItemId(entry.kind, entry.key);
+      if (targetId === itemId) return state;
+      if (state.items[targetId]) {
+        return focusExisting(canvasReducer(state, canvasActions.closeItem(itemId)), targetId);
+      }
+      return replaceInPlace(state, current, newItem(entry.kind, entry.key, entry.title, entry.data, now, history.slice(0, -1)));
+    }
     case `${P}closeItem`: {
       const { itemId } = action.payload;
       if (!state.items[itemId]) return state;
@@ -861,7 +953,8 @@ var CANVAS_WEB_LAYOUT_RULES = {
   defaultWidth: CANVAS_DEFAULT_WIDTH,
   minWidth: CANVAS_MIN_WIDTH,
   centreMinWidth: 420,
-  stackSplit: 0.5,
+  // Split down 70/30 like the desktop: what opens below (notifications, a feed) is the smaller pane.
+  stackSplit: 0.7,
   sideSplit: 0.5,
   paneMinWidth: 0
 };
@@ -994,7 +1087,8 @@ function createCanvasController(options) {
     presentationListeners: /* @__PURE__ */ new Set(),
     views: /* @__PURE__ */ new Map(),
     started: /* @__PURE__ */ new Map(),
-    sessionStop: null
+    sessionStop: null,
+    launcherSeq: 0
   };
   return view(shared, canvasWindowId(options.windowId ?? CANVAS_MAIN_WINDOW));
 }
@@ -1009,6 +1103,36 @@ function view(shared, windowId) {
     for (const listener of [...shared.presentationListeners]) listener();
   };
   const shareFor = (orientation) => orientation === "vertical" ? rules.stackSplit : rules.sideSplit;
+  const acceptable = (input) => {
+    if (input.kind !== CANVAS_LAUNCHER_KIND && options.isKnownKind && !options.isKnownKind(input.kind)) {
+      onError({ code: "unknown-kind", message: `No canvas kind "${input.kind}" is registered.`, detail: input });
+      return false;
+    }
+    if (input.data !== void 0) {
+      const bad = findNonJson(input.data);
+      if (bad) {
+        onError({
+          code: "non-json-data",
+          message: `Canvas data for "${input.kind}" must be plain JSON; ${bad} is not.`,
+          detail: { kind: input.kind, key: input.key }
+        });
+        return false;
+      }
+    }
+    return true;
+  };
+  const preferredTargetFor = (input) => {
+    const preferred = options.preferredTarget?.(input.kind);
+    if (!preferred || preferred === "focused") return "focused";
+    const state = store.getState();
+    if (canvasItemId(input.kind, input.key) in state.items) return "focused";
+    const frame2 = canvasWindowFrame(state, input.windowId ?? windowId);
+    if (!frame2?.isOpen) return "focused";
+    const panes = listPaneIds(frame2.layout);
+    const holding = panes.find((paneId) => state.panes[paneId]?.itemIds.some((id) => state.items[id]?.kind === input.kind));
+    if (holding) return { paneId: holding };
+    return state.panes[frame2.focusedPaneId]?.activeItemId ? preferred : "focused";
+  };
   const controller = {
     store,
     windowId,
@@ -1016,24 +1140,11 @@ function view(shared, windowId) {
     forWindow: (id) => view(shared, canvasWindowId(id)),
     getState: () => store.getState(),
     open(input) {
-      if (options.isKnownKind && !options.isKnownKind(input.kind)) {
-        onError({ code: "unknown-kind", message: `No canvas kind "${input.kind}" is registered.`, detail: input });
-        return null;
-      }
-      if (input.data !== void 0) {
-        const bad = findNonJson(input.data);
-        if (bad) {
-          onError({
-            code: "non-json-data",
-            message: `Canvas data for "${input.kind}" must be plain JSON; ${bad} is not.`,
-            detail: { kind: input.kind, key: input.key }
-          });
-          return null;
-        }
-      }
-      const target = input.target ?? "focused";
+      if (!acceptable(input)) return null;
+      const target = input.target ?? preferredTargetFor(input);
       const splitShare = target === "split-down" ? rules.stackSplit : target === "split-right" ? rules.sideSplit : void 0;
-      const resolved = input.windowId || windowId === CANVAS_MAIN_WINDOW ? input : { ...input, windowId };
+      const withTarget = input.target === target ? input : { ...input, target };
+      const resolved = withTarget.windowId || windowId === CANVAS_MAIN_WINDOW ? withTarget : { ...withTarget, windowId };
       dispatch(canvasActions.open(resolved, splitShare === void 0 ? void 0 : { splitShare }));
       return canvasItemId(input.kind, input.key);
     },
@@ -1049,6 +1160,34 @@ function view(shared, windowId) {
       dispatch(canvasActions.update(itemId, patch));
       return true;
     },
+    navigate(itemId, to) {
+      if (!store.getState().items[itemId] || !acceptable(to)) return null;
+      dispatch(canvasActions.navigate(itemId, to));
+      const shown = canvasItemId(to.kind, to.key);
+      return shown in store.getState().items ? shown : null;
+    },
+    back(itemId) {
+      const history = store.getState().items[itemId]?.history ?? [];
+      const entry = history[history.length - 1];
+      if (!entry) return null;
+      dispatch(canvasActions.back(itemId));
+      return canvasItemId(entry.kind, entry.key);
+    },
+    newTab(paneId) {
+      const state = store.getState();
+      const frame2 = canvasWindowFrame(state, windowId);
+      const target = paneId && state.panes[paneId] ? paneId : frame2?.focusedPaneId ?? state.focusedPaneId;
+      const existing = state.panes[target]?.itemIds.find((id) => state.items[id]?.kind === CANVAS_LAUNCHER_KIND);
+      if (existing) {
+        dispatch(canvasActions.activate(existing));
+        dispatch(canvasActions.setOpen(true, canvasWindowOfItem(store.getState(), existing) ?? windowId));
+        return existing;
+      }
+      shared.launcherSeq += 1;
+      const key = `${Date.now().toString(36)}-${shared.launcherSeq}`;
+      dispatch(canvasActions.open({ kind: CANVAS_LAUNCHER_KIND, key, target: { paneId: target }, ...windowId === CANVAS_MAIN_WINDOW ? {} : { windowId } }));
+      return canvasItemId(CANVAS_LAUNCHER_KIND, key);
+    },
     rekey(itemId, key) {
       const item = store.getState().items[itemId];
       if (!item) return null;
@@ -1312,6 +1451,41 @@ function selectCanvasWindows(s) {
 }
 var selectCanvasExtraWindow = (s, windowId) => s.windows?.[windowId];
 var selectCanvasWindowOfItem = canvasWindowOfItem;
+var NO_HISTORY = Object.freeze([]);
+function selectCanvasItemHistory(s, itemId) {
+  return s.items[itemId]?.history ?? NO_HISTORY;
+}
+var selectCanvasCanGoBack = (s, itemId) => (s.items[itemId]?.history?.length ?? 0) > 0;
+
+// src/core/presentation.ts
+var CANVAS_NARROW_WIDTH = 480;
+var SQUARE_BAND = 1.2;
+function canvasOrientation(width, height) {
+  if (!(width > 0) || !(height > 0)) return "square";
+  const ratio = width / height;
+  if (ratio >= SQUARE_BAND) return "landscape";
+  if (ratio <= 1 / SQUARE_BAND) return "portrait";
+  return "square";
+}
+function canvasPresentation(input) {
+  const width = Math.max(0, Math.round(input.width));
+  const height = Math.max(0, Math.round(input.height));
+  return {
+    host: "canvas",
+    width,
+    height,
+    orientation: canvasOrientation(width, height),
+    isNarrow: width > 0 && width < CANVAS_NARROW_WIDTH,
+    isFullscreen: input.isFullscreen,
+    paneCount: Math.max(1, input.paneCount)
+  };
+}
+function preferredFlowDirection(presentation) {
+  if (!presentation) return "horizontal";
+  if (presentation.orientation === "portrait") return "vertical";
+  if (presentation.orientation === "landscape") return "horizontal";
+  return presentation.isNarrow ? "vertical" : "horizontal";
+}
 
 // src/core/toggleKind.ts
 var CANVAS_DEFAULT_KEY = "default";
@@ -1354,15 +1528,20 @@ export {
   CANVAS_DEFAULT_KEY,
   CANVAS_DEFAULT_WIDTH,
   CANVAS_DESKTOP_LAYOUT_RULES,
+  CANVAS_HISTORY_LIMIT,
+  CANVAS_LAUNCHER_KIND,
   CANVAS_MAIN_WINDOW,
   CANVAS_MIN_SPLIT_FRACTION,
   CANVAS_MIN_WIDTH,
+  CANVAS_NARROW_WIDTH,
   CANVAS_SHORTCUTS,
   CANVAS_STORAGE_KEY,
   CANVAS_WEB_LAYOUT_RULES,
   bindCanvasToReduxStore,
   canvasActions,
   canvasItemId,
+  canvasOrientation,
+  canvasPresentation,
   canvasReducer,
   canvasShortcutHint,
   canvasWindowFrame,
@@ -1388,10 +1567,12 @@ export {
   matchesCanvasAccelerator,
   normalizeSizes,
   parseCanvasItemId,
+  preferredFlowDirection,
   resolveCanvasLayoutRules,
   runCanvasCommand,
   sanitizeCanvasSnapshot,
   selectCanvasActiveItem,
+  selectCanvasCanGoBack,
   selectCanvasExtraWindow,
   selectCanvasFocusedPaneId,
   selectCanvasIsFullscreen,
@@ -1399,6 +1580,7 @@ export {
   selectCanvasIsOpen,
   selectCanvasItem,
   selectCanvasItemCount,
+  selectCanvasItemHistory,
   selectCanvasKindVisibility,
   selectCanvasLayout,
   selectCanvasPane,