@ai-matrx/canvas 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.5.0
+
+Owner feedback after using the canvas live (Arman, 2026-10-02): a stable canvas that never dismounts, no UI traps, readable tabs, the shell's motion, content that knows its shape, and the pieces web and desktop both need.
+
+- **Stable bodies (never dismount).** Every open item's body is rendered ONCE, in a body layer at the column root keyed by the item's instance, and placed over its pane's body slot by measured rect (DOM bodies and native bodies alike: a body on a slot). A tab switch hides it (`visibility` + `content-visibility: hidden` + `inert`: state and scroll kept); a split, a move between panes, a width drag and expand re-place it; putting the canvas away keeps it. A body mounts the first time it is shown and stays mounted until its tab closes. A rekeyed draft keeps its body (`CanvasItem.instance`). Moving a tab to another window remounts it (a different column). Bodies re-render only when their own item, pane, focus, visibility or presentation changes.
+- **`unmountWhenHidden`** (kind field): opt out for genuinely heavy hidden bodies. **`keepAlive` is deprecated and does nothing** — staying mounted is the default.
+- **`CanvasKindProps.isVisible`**: on screen right now (active tab, canvas open) — pause costly work while false.
+- **The column never unmounts.** Put away, it is 0 wide, `inert`, `aria-hidden` and hidden after the slide; `useCanvasColumnWidth()` still reads 0.
+- **No UI traps.** Every pane header has a **"+" New tab** (opens the launcher as a tab; a pane holds one). A lone tab shown as a title has **its own close**. **Tab history:** `controller.navigate(itemId, { kind, key, title?, data? })` replaces a tab's content in place and records where it was (`CanvasItem.history`, JSON, persisted, at most `CANVAS_HISTORY_LIMIT` = 50); the header shows **Back** while the active tab has history; `controller.back(itemId)`. Choosing in the launcher navigates the launcher tab (Back returns to it); choosing in an empty pane's launcher does the same. Identity still holds: navigating to an item open elsewhere focuses it there — a launcher tab then closes, any other tab keeps what it shows; Back to an item opened elsewhere since focuses it and closes the step. Reducer actions `navigate` / `back`, `controller.newTab(paneId?)`, selectors `selectCanvasCanGoBack` / `selectCanvasItemHistory`, `CANVAS_LAUNCHER_KIND`.
+- **Dense tabs.** 12.5px text, 14px icon, 6px side padding, 26px tall; tabs shrink evenly from 8rem to a 3.25rem floor, the active tab keeps icon + ~10 letters, the close is overlaid (no width while hidden; the title fades under it), the strip scrolls sideways with the wheel and keeps the active tab in view.
+- **Motion.** Open, put away, expand and restore animate the column's width on `--mxc-motion-duration` / `--mxc-motion-ease` (tokens.css: 600ms, `cubic-bezier(0.4, 0, 0.2, 1)` — the AI Matrx shell sidebar's slide); the content keeps its width so it slides instead of reflowing; off while an edge is dragged and under `prefers-reduced-motion`. Native views are re-measured every frame of the slide.
+- **Presentation primitive.** `CanvasKindProps.presentation = { host: "canvas", width, height, orientation: "portrait" | "landscape" | "square", isNarrow, isFullscreen, paneCount }`, live from the slot; `useCanvasPresentation()` gives any nested component the same value (null outside the canvas); `preferredFlowDirection(presentation)` → `"vertical" | "horizontal"`; pure `canvasPresentation`, `canvasOrientation`, `CANVAS_NARROW_WIDTH` in the core.
+- **Contextual launcher entries.** `useCanvasLauncherEntry({ kind, key, data?, title?, icon? })` offers a page's own thing in the launcher while it is mounted ("On this page", before the global kinds); entries for unregistered kinds are not offered.
+- **`preferredTarget`** (kind field): `"split-down" | "split-right" | "focused"` — where a NEW item of the kind opens while the canvas already shows something; a pane already holding the kind takes it; an explicit `target` wins. `open` and `toggleKind` honour it (controller option `preferredTarget`).
+- **`CanvasKindIcons`**: a header's cluster of kind toggles (`kinds: (string | { kind, key?, data?, title?, whenVisible?, label? })[]`, `variant`), each pressed while its item is in front; unregistered kinds draw nothing.
+- **Web split-down is 70/30** (`CANVAS_WEB_LAYOUT_RULES.stackSplit` 0.5 → 0.7), like the desktop: what opens below is the smaller pane.
+
+### Consumer action
+
+- A host that reflows beside the docked column (`right: var(--shell-canvas-w)`, a grid track) transitions that property with `var(--mxc-motion-duration) var(--mxc-motion-ease)`, turns the transition off under `:root[data-mxc-resizing]` and under `prefers-reduced-motion: reduce` (README § Motion). A shell that hid the app in full screen keeps its docked inset and lets the column grow over it.
+- Delete `keepAlive` from kinds (no-op). Add `unmountWhenHidden: true` only for a body that must not stay mounted.
+- Code that builds `CanvasKindProps` itself passes `presentation` and `isVisible`.
+- Code that read `.mxc-item[hidden]` or expected `.mxc-column` to be absent when put away reads `[data-visible]` on `.mxc-item-host` and `[data-open]` on `.mxc-column`.
+- A host-side "open new tab below" rule (web `toolCanvas` `target: "split-down"`) becomes the kind's `preferredTarget`.
+- Code iterating `state.items` skips `CANVAS_LAUNCHER_KIND` ("New tab") items where a launcher is not a real thing.
+- Desktop: the toolbar icon cluster can be `CanvasKindIcons`; a kind body that drew its own back button for in-canvas navigation can use `controller.navigate` / Back.
+
+## 0.4.0
+
+- **`CanvasKind.Toolbar`** — a toolbar ROW between the pane header and the body, rendered for the active item only (a browser's back / forward / reload / address / screenshot / open in browser / new tab), so the header keeps just the tab strip and pane controls. Always DOM and never covered by a native view: a `body: "native"` frame is measured below it. A toolbar that throws renders nothing instead of taking the pane down. Requested by the desktop session.
+
+### Consumer action
+
+- Kinds that crammed a toolbar into `HeaderLeading` (the desktop browser) move it to `Toolbar`.
+
 ## 0.3.0
 
 - **Toggle or focus a kind** — what a toolbar icon or a quick-tool launcher does. `toggleKind(controller, { kind, key?, data?, title?, whenVisible? })`: absent → open and reveal; behind another tab or canvas put away → bring it forward; in front → close it (default) or put the canvas away (`whenVisible: "hide"`). `data` seeds only a new item. `selectCanvasKindVisibility(state, kind, key?)` returns `"absent" | "background" | "visible"` (a primitive — safe in useSyncExternalStore / useSelector), and the React hook `useCanvasKindToggle(input)` gives `{ visibility, isOpen, isVisible, toggle }` for an icon button's active state. Key defaults to `CANVAS_DEFAULT_KEY` ("default").

package/README.md

@@ -29,7 +29,6 @@ defineCanvasKind<{ sessionKey: string }>({
   restore: "session",          // closing detaches; a restore or a move reattaches
   onAttach: ({ sessionKey, reason }) => attach(sessionKey, reason),
   onDetach: ({ sessionKey }) => detach(sessionKey), // never kill here
-  keepAlive: true,
   HeaderLeading: NewTerminalButton, // "+ new terminal", a browser bar…
   HeaderAction: ClearButton,
   unavailable: () => (backendUp() ? null : "Terminal · next release"),
@@ -38,6 +37,72 @@ defineCanvasKind<{ sessionKey: string }>({
 
 `body: "native"` makes the body a placeholder whose frame the host receives (below).
 
+## Bodies never dismount
+
+Every open item's body is rendered once, in the column's body layer, and placed over its pane by measured rect. Switching tabs hides it; splitting, moving a tab between panes, dragging the width, expanding and putting the canvas away only re-place or hide it. React state, focus and scroll survive everything but closing the tab. A body mounts the first time it is shown. `isVisible` tells it whether it is on screen (pause polling while false); `unmountWhenHidden: true` opts a genuinely heavy body out.
+
+## Content that knows its shape
+
+```tsx
+function GraphView({ presentation }: CanvasKindProps) {   // or useCanvasPresentation() anywhere inside the body
+  return <Graph direction={preferredFlowDirection(presentation) === "vertical" ? "TB" : "LR"} />;
+}
+```
+
+`presentation = { host: "canvas", width, height, orientation: "portrait" | "landscape" | "square", isNarrow, isFullscreen, paneCount }`, live. `useCanvasPresentation()` returns it to any nested component and `null` outside the canvas. When you have a lot of vertical space and little horizontal space, adapt: lay graphs, timelines and card rows out top to bottom, stack side-by-side columns, shorten toolbars.
+
+## Tabs, New tab and Back
+
+Every pane header has "+" (a launcher tab). Choosing in the launcher NAVIGATES that tab in place, so the header offers Back. Do the same from a kind:
+
+```ts
+canvas.navigate(item.id, { kind: "doc", key: docId, data: { docId } }); // records history; Back returns
+canvas.back(item.id);
+```
+
+Navigating to something already open elsewhere focuses it there (a launcher tab closes; any other tab keeps what it shows). History is plain JSON and persists. A lone tab shown as a title keeps its own close.
+
+## A page's own launcher entries
+
+```tsx
+useCanvasLauncherEntry({ kind: "documents", key: conversationId, data: { conversationId }, title: "This chat's documents" });
+```
+
+Shown first ("On this page") while the calling component is mounted.
+
+## Where a new item opens
+
+```tsx
+defineCanvasKind({ id: "notifications", preferredTarget: "split-down", /* … */ });
+```
+
+While the canvas already shows something, a NEW item of the kind opens below (the layout rules' split share, 70/30) or beside; a pane already showing the kind takes it. An explicit `target` wins. `open` and `toggleKind` honour it.
+
+## A header's tool icons
+
+```tsx
+<CanvasKindIcons kinds={["terminal", "review", { kind: "browser", label: "Browser" }]} variant="glass" />
+```
+
+Each icon toggles or focuses its kind and is pressed while its item is in front.
+
+## Motion
+
+The column animates its width on `--mxc-motion-duration` / `--mxc-motion-ease` (tokens.css: 600ms, `cubic-bezier(0.4, 0, 0.2, 1)`), with its content keeping its width so it slides. A host that reflows beside it moves in lockstep on the same pair:
+
+```css
+.app-shell { right: var(--canvas-w); transition: right var(--mxc-motion-duration) var(--mxc-motion-ease); }
+:root[data-mxc-resizing] .app-shell { transition: none; }               /* the edge is being dragged */
+@media (prefers-reduced-motion: reduce) { .app-shell { transition: none; } }
+```
+
+`<CanvasFrame>` needs nothing: its main area is a flex sibling and follows the column every frame.
+
+## A toolbar row under the header
+
+A kind's `Toolbar` renders between the pane header and its body for the active
+item (a browser bar). It is DOM, and a native body's frame is measured below it.
+
 ## Toolbar icons: toggle or focus a kind
 
 ```tsx

package/dist/index.cjs

@@ -23,15 +23,20 @@ __export(src_exports, {
   CANVAS_DEFAULT_KEY: () => CANVAS_DEFAULT_KEY,
   CANVAS_DEFAULT_WIDTH: () => CANVAS_DEFAULT_WIDTH,
   CANVAS_DESKTOP_LAYOUT_RULES: () => CANVAS_DESKTOP_LAYOUT_RULES,
+  CANVAS_HISTORY_LIMIT: () => CANVAS_HISTORY_LIMIT,
+  CANVAS_LAUNCHER_KIND: () => CANVAS_LAUNCHER_KIND,
   CANVAS_MAIN_WINDOW: () => CANVAS_MAIN_WINDOW,
   CANVAS_MIN_SPLIT_FRACTION: () => CANVAS_MIN_SPLIT_FRACTION,
   CANVAS_MIN_WIDTH: () => CANVAS_MIN_WIDTH,
+  CANVAS_NARROW_WIDTH: () => CANVAS_NARROW_WIDTH,
   CANVAS_SHORTCUTS: () => CANVAS_SHORTCUTS,
   CANVAS_STORAGE_KEY: () => CANVAS_STORAGE_KEY,
   CANVAS_WEB_LAYOUT_RULES: () => CANVAS_WEB_LAYOUT_RULES,
   bindCanvasToReduxStore: () => bindCanvasToReduxStore,
   canvasActions: () => canvasActions,
   canvasItemId: () => canvasItemId,
+  canvasOrientation: () => canvasOrientation,
+  canvasPresentation: () => canvasPresentation,
   canvasReducer: () => canvasReducer,
   canvasShortcutHint: () => canvasShortcutHint,
   canvasWindowFrame: () => canvasWindowFrame,
@@ -57,10 +62,12 @@ __export(src_exports, {
   matchesCanvasAccelerator: () => matchesCanvasAccelerator,
   normalizeSizes: () => normalizeSizes,
   parseCanvasItemId: () => parseCanvasItemId,
+  preferredFlowDirection: () => preferredFlowDirection,
   resolveCanvasLayoutRules: () => resolveCanvasLayoutRules,
   runCanvasCommand: () => runCanvasCommand,
   sanitizeCanvasSnapshot: () => sanitizeCanvasSnapshot,
   selectCanvasActiveItem: () => selectCanvasActiveItem,
+  selectCanvasCanGoBack: () => selectCanvasCanGoBack,
   selectCanvasExtraWindow: () => selectCanvasExtraWindow,
   selectCanvasFocusedPaneId: () => selectCanvasFocusedPaneId,
   selectCanvasIsFullscreen: () => selectCanvasIsFullscreen,
@@ -68,6 +75,7 @@ __export(src_exports, {
   selectCanvasIsOpen: () => selectCanvasIsOpen,
   selectCanvasItem: () => selectCanvasItem,
   selectCanvasItemCount: () => selectCanvasItemCount,
+  selectCanvasItemHistory: () => selectCanvasItemHistory,
   selectCanvasKindVisibility: () => selectCanvasKindVisibility,
   selectCanvasLayout: () => selectCanvasLayout,
   selectCanvasPane: () => selectCanvasPane,
@@ -85,6 +93,8 @@ module.exports = __toCommonJS(src_exports);
 
 // 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;
@@ -250,6 +260,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 } }),
@@ -446,6 +460,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;
 }
@@ -493,7 +564,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();
@@ -567,7 +638,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;
@@ -616,6 +687,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;
@@ -946,7 +1046,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
 };
@@ -1079,7 +1180,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));
 }
@@ -1094,6 +1196,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,
@@ -1101,24 +1233,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);
     },
@@ -1134,6 +1253,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;
@@ -1397,6 +1544,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";