From 211e1934a6f7c1adb590b229b23fb80493990818 Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Thu, 7 Nov 2024 16:00:47 +0100
Subject: [PATCH 01/15] Pasting?

---
 app/gui/src/project-view/bindings.ts          |  1 +
 .../components/DocumentationEditor.vue        | 64 +++++++++++++++++--
 .../components/MarkdownEditor.vue             | 13 +++-
 .../MarkdownEditor/MarkdownEditorImpl.vue     |  9 +++
 .../src/project-view/stores/project/index.ts  |  9 +++
 app/gui/src/project-view/util/toast.ts        | 25 +++++++-
 6 files changed, 113 insertions(+), 8 deletions(-)

diff --git a/app/gui/src/project-view/bindings.ts b/app/gui/src/project-view/bindings.ts
index 210094aeb62c..63c00ee04498 100644
--- a/app/gui/src/project-view/bindings.ts
+++ b/app/gui/src/project-view/bindings.ts
@@ -12,6 +12,7 @@ export const codeEditorBindings = defineKeybinds('code-editor', {
 export const documentationEditorBindings = defineKeybinds('documentation-editor', {
   toggle: ['Mod+D'],
   openLink: ['Mod+PointerMain'],
+  pasteImage: ['Mod+V'],
 })
 
 export const interactionBindings = defineKeybinds('current-interaction', {
diff --git a/app/gui/src/project-view/components/DocumentationEditor.vue b/app/gui/src/project-view/components/DocumentationEditor.vue
index fc19d6b70888..81a850c81533 100644
--- a/app/gui/src/project-view/components/DocumentationEditor.vue
+++ b/app/gui/src/project-view/components/DocumentationEditor.vue
@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import { documentationEditorBindings } from '@/bindings'
 import FullscreenButton from '@/components/FullscreenButton.vue'
 import MarkdownEditor from '@/components/MarkdownEditor.vue'
 import { fetcherUrlTransformer } from '@/components/MarkdownEditor/imageUrlTransformer'
@@ -6,7 +7,8 @@ import WithFullscreenMode from '@/components/WithFullscreenMode.vue'
 import { useGraphStore } from '@/stores/graph'
 import { useProjectStore } from '@/stores/project'
 import type { ToValue } from '@/util/reactivity'
-import { ref, toRef, toValue, watch } from 'vue'
+import { useToast } from '@/util/toast'
+import { ComponentInstance, ref, toRef, toValue, watch } from 'vue'
 import type { Path } from 'ydoc-shared/languageServerTypes'
 import { Err, Ok, mapOk, withContext, type Result } from 'ydoc-shared/util/data/result'
 import * as Y from 'yjs'
@@ -19,13 +21,16 @@ const emit = defineEmits<{
 }>()
 
 const toolbarElement = ref<HTMLElement>()
+const markdownEditor = ref<ComponentInstance<typeof MarkdownEditor>>()
 
 const graphStore = useGraphStore()
 const projectStore = useProjectStore()
-const { transformImageUrl } = useDocumentationImages(
+const { transformImageUrl, uploadImage } = useDocumentationImages(
   toRef(graphStore, 'modulePath'),
+  // TODO: is this needed?
   projectStore.readFileBinary,
 )
+const uploadErrorToast = useToast.error()
 
 function useDocumentationImages(
   modulePath: ToValue<Path | undefined>,
@@ -54,6 +59,8 @@ function useDocumentationImages(
     return pathUniqueId(path)
   }
 
+  const uploadedImages = new Map<string, Promise<Blob>>()
+
   const transformImageUrl = fetcherUrlTransformer(
     async (url: string) => {
       const path = await urlToPath(url)
@@ -66,12 +73,43 @@ function useDocumentationImages(
     async (path) => {
       return withContext(
         () => `Loading documentation image (${pathDebugRepr(path)})`,
-        async () => await readFileBinary(path),
+        () => {
+          const uploaded = uploadedImages.get(pathUniqueId(path))
+          return uploaded?.then((blob) => Ok(blob)) ?? readFileBinary(path)
+        },
       )
     },
   )
 
-  return { transformImageUrl }
+  function uploadImage(name: string, blob: Promise<Blob>) {
+    if (!markdownEditor.value || !markdownEditor.value.loaded) {
+      console.error('Tried to upload image while mardown editor is still not loaded')
+      return
+    }
+    // TODO: check for name conflicts.
+    markdownEditor.value.putText(`![Image](/images/${name})`)
+    projectStore.projectRootId.then((rootId) => {
+      if (!rootId) {
+        uploadErrorToast.show('Cannot upload image: unknown project file tree root.')
+        return
+      }
+      const path: Path = {
+        rootId,
+        segments: ['images', name],
+      }
+      const id = pathUniqueId(path)
+      uploadedImages.set(id, blob)
+      blob
+        .then(async (blob) => {
+          const result = await projectStore.writeFileBinary(path, blob)
+          if (!result.ok) uploadErrorToast.reportError(result.error, 'Failed to upload image')
+        })
+        .catch((err) => uploadErrorToast.show(`Failed to upload image: ${err}`))
+        .finally(() => uploadedImages.delete(id))
+    })
+  }
+
+  return { transformImageUrl, uploadImage }
 }
 
 const fullscreen = ref(false)
@@ -81,6 +119,22 @@ watch(
   () => fullscreen.value || fullscreenAnimating.value,
   (fullscreenOrAnimating) => emit('update:fullscreen', fullscreenOrAnimating),
 )
+
+const handler = documentationEditorBindings.handler({
+  pasteImage: () => {
+    window.navigator.clipboard.read().then(async (items) => {
+      for (const item of items) {
+        const imageType = item.types.find((type) => type.startsWith('image/'))
+        if (imageType) {
+          // TODO: better extensions
+          const ext = imageType.slice('image/'.length)
+          uploadImage(`image${ext}`, item.getType(imageType))
+          break
+        }
+      }
+    })
+  },
+})
 </script>
 
 <template>
@@ -91,9 +145,11 @@ watch(
       </div>
       <div class="scrollArea">
         <MarkdownEditor
+          ref="markdownEditor"
           :yText="yText"
           :transformImageUrl="transformImageUrl"
           :toolbarContainer="toolbarElement"
+          @keydown="handler"
         />
       </div>
     </div>
diff --git a/app/gui/src/project-view/components/MarkdownEditor.vue b/app/gui/src/project-view/components/MarkdownEditor.vue
index c1a0821b87db..da22315816c8 100644
--- a/app/gui/src/project-view/components/MarkdownEditor.vue
+++ b/app/gui/src/project-view/components/MarkdownEditor.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { UrlTransformer } from '@/components/MarkdownEditor/imageUrlTransformer'
-import { defineAsyncComponent } from 'vue'
+import { ComponentInstance, computed, defineAsyncComponent, ref } from 'vue'
 import * as Y from 'yjs'
 
 const props = defineProps<{
@@ -9,13 +9,22 @@ const props = defineProps<{
   toolbarContainer: HTMLElement | undefined
 }>()
 
+const inner = ref<ComponentInstance<typeof LazyMarkdownEditor>>()
+
 const LazyMarkdownEditor = defineAsyncComponent(
   () => import('@/components/MarkdownEditor/MarkdownEditorImpl.vue'),
 )
+
+defineExpose({
+  loaded: computed(() => inner.value != null),
+  putText: (text: string) => {
+    inner.value?.putText(text)
+  },
+})
 </script>
 
 <template>
   <Suspense>
-    <LazyMarkdownEditor v-bind="props" />
+    <LazyMarkdownEditor ref="inner" v-bind="props" />
   </Suspense>
 </template>
diff --git a/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue b/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
index 605128a10bcb..2b33ae05f2dc 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
+++ b/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
@@ -48,6 +48,15 @@ onMounted(() => {
 })
 
 const editing = ref(false)
+
+defineExpose({
+  putText: (text: string) => {
+    const range = editorView.state.selection.ranges[0]!
+    editorView.dispatch({
+      changes: { from: range.from, to: range.to, insert: text },
+    })
+  },
+})
 </script>
 
 <template>
diff --git a/app/gui/src/project-view/stores/project/index.ts b/app/gui/src/project-view/stores/project/index.ts
index 0ea46a61f6a1..c3c490b975e8 100644
--- a/app/gui/src/project-view/stores/project/index.ts
+++ b/app/gui/src/project-view/stores/project/index.ts
@@ -391,6 +391,14 @@ export const { provideFn: provideProjectStore, injectFn: useProjectStore } = cre
       return Ok(new Blob([contents]))
     }
 
+    async function writeFileBinary(path: Path, content: Blob): Promise<Result> {
+      const result = await dataConnection.writeFile(path, await content.arrayBuffer())
+      if (result instanceof DataError) {
+        return Err(result.message() ?? 'Failed to write file.')
+      }
+      return Ok()
+    }
+
     return proxyRefs({
       setObservedFileName(name: string) {
         observedFileName.value = name
@@ -415,6 +423,7 @@ export const { provideFn: provideProjectStore, injectFn: useProjectStore } = cre
       lsRpcConnection: markRaw(lsRpcConnection),
       dataConnection: markRaw(dataConnection),
       readFileBinary,
+      writeFileBinary,
       useVisualizationData,
       isRecordingEnabled,
       stopCapturingUndo,
diff --git a/app/gui/src/project-view/util/toast.ts b/app/gui/src/project-view/util/toast.ts
index 92768054532a..2402d07d2d26 100644
--- a/app/gui/src/project-view/util/toast.ts
+++ b/app/gui/src/project-view/util/toast.ts
@@ -1,6 +1,6 @@
-// We are using `react-toastify`, since we share toast environment with dashboard.
 import type { ResultError } from '@/util/data/result'
 import { uuidv4 } from 'lib0/random'
+// We are using `react-toastify`, since we share toast environment with dashboard.
 import { toast, type ToastContent, type ToastOptions, type TypeOptions } from 'react-toastify'
 import { onScopeDispose } from 'vue'
 
@@ -15,7 +15,25 @@ export interface UseToastOptions extends ToastOptions {
   outliveScope?: boolean
 }
 
-/** TODO: Add docs */
+/**
+ * Composable for new toast - a pop-up message displayed to the user.
+ *
+ * ```ts
+ * // useToast.error is an equivalent of useToast(type: 'error').
+ * // There's also useToast.info, useToast.warning and useToast.success.
+ * const toastLspError = useToast.error()
+ * // Every `useToast` allow displaying only one message at once, so
+ * // here we create separate toast for every "topic".
+ * const toastExecutionFailed = useToast.error()
+ * const toastUserActionFailed = useToast.error()
+ * // Toast are automatically closed after some time. Here we suppress this.
+ * const toastStartup = useToast.info({ autoClose: false })
+ * const toastConnectionLost = useToast.error({ autoClose: false })
+ *
+ * ```
+ *
+ * For details, read about `toastify` library.
+ */
 export function useToast(options: UseToastOptions = {}) {
   const id = makeToastId()
   if (options?.outliveScope !== true) {
@@ -23,15 +41,18 @@ export function useToast(options: UseToastOptions = {}) {
   }
 
   return {
+    /** Show or update toast. */
     show(content: ToastContent) {
       if (toast.isActive(id)) toast.update(id, { ...options, render: content })
       else toast(content, { ...options, toastId: id })
     },
+    /** A helper for reporting {@link ResultError} to both toast and console. */
     reportError<E>(result: ResultError<E>, preamble?: string) {
       const msg = result.message(preamble)
       console.error(msg)
       this.show(msg)
     },
+    /** Dismiss the displayed toast. */
     dismiss() {
       toast.dismiss(id)
     },

From ceb218660a30637d344af079de00a13a8d15fb33 Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Fri, 8 Nov 2024 11:45:02 +0100
Subject: [PATCH 02/15] Pasting!

---
 .../src/project-view/components/DocumentationEditor.vue    | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/app/gui/src/project-view/components/DocumentationEditor.vue b/app/gui/src/project-view/components/DocumentationEditor.vue
index 81a850c81533..92baf4b9a06f 100644
--- a/app/gui/src/project-view/components/DocumentationEditor.vue
+++ b/app/gui/src/project-view/components/DocumentationEditor.vue
@@ -43,7 +43,7 @@ function useDocumentationImages(
     }
     const appliedUrl = new URL(url, `file:///${modulePathValue.segments.join('/')}`)
     if (appliedUrl.protocol === 'file:') {
-      const segments = appliedUrl.pathname.split('/')
+      const segments = appliedUrl.pathname.split('/').slice(1)
       return Ok({ rootId: modulePathValue.rootId, segments })
     } else {
       // Not a relative URL, custom fetching not needed.
@@ -128,7 +128,7 @@ const handler = documentationEditorBindings.handler({
         if (imageType) {
           // TODO: better extensions
           const ext = imageType.slice('image/'.length)
-          uploadImage(`image${ext}`, item.getType(imageType))
+          uploadImage(`image.${ext}`, item.getType(imageType))
           break
         }
       }
@@ -143,13 +143,12 @@ const handler = documentationEditorBindings.handler({
       <div ref="toolbarElement" class="toolbar">
         <FullscreenButton v-model="fullscreen" />
       </div>
-      <div class="scrollArea">
+      <div class="scrollArea" @keydown="handler">
         <MarkdownEditor
           ref="markdownEditor"
           :yText="yText"
           :transformImageUrl="transformImageUrl"
           :toolbarContainer="toolbarElement"
-          @keydown="handler"
         />
       </div>
     </div>

From 40176dd5d6ad95dc2cd69125426b4f80a62b1bbd Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Fri, 8 Nov 2024 15:11:29 +0100
Subject: [PATCH 03/15] Pasting!!!

---
 .../components/DocumentationEditor.vue        |  81 +++++++++----
 .../components/GraphEditor/upload.ts          | 111 ++++++++++--------
 .../MarkdownEditor/MarkdownEditorImpl.vue     |   1 +
 3 files changed, 117 insertions(+), 76 deletions(-)

diff --git a/app/gui/src/project-view/components/DocumentationEditor.vue b/app/gui/src/project-view/components/DocumentationEditor.vue
index 92baf4b9a06f..a885a8817ce3 100644
--- a/app/gui/src/project-view/components/DocumentationEditor.vue
+++ b/app/gui/src/project-view/components/DocumentationEditor.vue
@@ -12,6 +12,7 @@ import { ComponentInstance, ref, toRef, toValue, watch } from 'vue'
 import type { Path } from 'ydoc-shared/languageServerTypes'
 import { Err, Ok, mapOk, withContext, type Result } from 'ydoc-shared/util/data/result'
 import * as Y from 'yjs'
+import { pickUniqueName } from './GraphEditor/upload'
 
 const { yText } = defineProps<{
   yText: Y.Text
@@ -36,7 +37,7 @@ function useDocumentationImages(
   modulePath: ToValue<Path | undefined>,
   readFileBinary: (path: Path) => Promise<Result<Blob>>,
 ) {
-  async function urlToPath(url: string): Promise<Result<Path> | undefined> {
+  function urlToPath(url: string): Result<Path> | undefined {
     const modulePathValue = toValue(modulePath)
     if (!modulePathValue) {
       return Err('Current module path is unknown.')
@@ -81,32 +82,40 @@ function useDocumentationImages(
     },
   )
 
-  function uploadImage(name: string, blob: Promise<Blob>) {
+  async function uploadImage(name: string, blobPromise: Promise<Blob>) {
+    const rootId = await projectStore.projectRootId
+    if (!rootId) {
+      uploadErrorToast.show('Cannot upload image: unknown project file tree root.')
+      return
+    }
     if (!markdownEditor.value || !markdownEditor.value.loaded) {
       console.error('Tried to upload image while mardown editor is still not loaded')
       return
     }
-    // TODO: check for name conflicts.
-    markdownEditor.value.putText(`![Image](/images/${name})`)
-    projectStore.projectRootId.then((rootId) => {
-      if (!rootId) {
-        uploadErrorToast.show('Cannot upload image: unknown project file tree root.')
-        return
-      }
-      const path: Path = {
+    const filename = await pickUniqueName(
+      projectStore.lsRpcConnection,
+      {
         rootId,
-        segments: ['images', name],
-      }
-      const id = pathUniqueId(path)
-      uploadedImages.set(id, blob)
-      blob
-        .then(async (blob) => {
-          const result = await projectStore.writeFileBinary(path, blob)
-          if (!result.ok) uploadErrorToast.reportError(result.error, 'Failed to upload image')
-        })
-        .catch((err) => uploadErrorToast.show(`Failed to upload image: ${err}`))
-        .finally(() => uploadedImages.delete(id))
-    })
+        segments: ['images'],
+      },
+      name,
+    )
+    if (!filename.ok) {
+      uploadErrorToast.reportError(filename.error)
+      return
+    }
+    markdownEditor.value.putText(`![Image](/images/${filename.value})`)
+    const path: Path = { rootId, segments: ['images', filename.value] }
+    const id = pathUniqueId(path)
+    uploadedImages.set(id, blobPromise)
+    try {
+      const blob = await blobPromise
+      const uploadResult = await projectStore.writeFileBinary(path, blob)
+      if (!uploadResult.ok)
+        uploadErrorToast.reportError(uploadResult.error, 'Failed to upload image')
+    } finally {
+      uploadedImages.delete(id)
+    }
   }
 
   return { transformImageUrl, uploadImage }
@@ -120,15 +129,35 @@ watch(
   (fullscreenOrAnimating) => emit('update:fullscreen', fullscreenOrAnimating),
 )
 
+const supportedImageTypes: Record<string, { extension: string }> = {
+  // List taken from https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types
+  'image/apng': { extension: 'apng' },
+  'image/avif': { extension: 'avif' },
+  'image/gif': { extension: 'gif' },
+  'image/jpeg': { extension: 'jpg' },
+  'image/png': { extension: 'png' },
+  'image/svg+xml': { extension: 'svg' },
+  'image/webp': { extension: 'webp' },
+  // Question: do we want to have BMP and ICO here?
+}
+
 const handler = documentationEditorBindings.handler({
   pasteImage: () => {
     window.navigator.clipboard.read().then(async (items) => {
+      if (markdownEditor.value == null) return
       for (const item of items) {
-        const imageType = item.types.find((type) => type.startsWith('image/'))
+        const textType = item.types.find((type) => type === 'text/plain')
+        if (textType) {
+          const blob = await item.getType(textType)
+          markdownEditor.value.putText(await blob.text())
+          break
+        }
+        const imageType = item.types.find((type) => type in supportedImageTypes)
         if (imageType) {
-          // TODO: better extensions
-          const ext = imageType.slice('image/'.length)
-          uploadImage(`image.${ext}`, item.getType(imageType))
+          const ext = supportedImageTypes[imageType]?.extension ?? ''
+          uploadImage(`image.${ext}`, item.getType(imageType)).catch((err) =>
+            uploadErrorToast.show(`Failed to upload image: ${err}`),
+          )
           break
         }
       }
diff --git a/app/gui/src/project-view/components/GraphEditor/upload.ts b/app/gui/src/project-view/components/GraphEditor/upload.ts
index b62330d6c275..044b7bddc58c 100644
--- a/app/gui/src/project-view/components/GraphEditor/upload.ts
+++ b/app/gui/src/project-view/components/GraphEditor/upload.ts
@@ -11,6 +11,64 @@ import { ErrorCode, RemoteRpcError } from 'ydoc-shared/languageServer'
 import type { Path, StackItem, Uuid } from 'ydoc-shared/languageServerTypes'
 import { Err, Ok, withContext, type Result } from 'ydoc-shared/util/data/result'
 
+/** Check if directory exists and try to create one if missing. */
+export async function ensureDirExists(rpc: LanguageServer, path: Path) {
+  const exists = await dirExists(rpc, path)
+  if (!exists.ok) return exists
+  if (exists.value) return Ok()
+
+  const name = path.segments.at(-1)
+  if (name == null) return Err('Cannot create context root')
+
+  return await withContext(
+    () => 'When creating directory for uploaded file',
+    async () => {
+      return await rpc.createFile({
+        type: 'Directory',
+        name,
+        path: { rootId: path.rootId, segments: path.segments.slice(0, -1) },
+      })
+    },
+  )
+}
+
+async function dirExists(rpc: LanguageServer, path: Path): Promise<Result<boolean>> {
+  const info = await rpc.fileInfo(path)
+  if (info.ok) return Ok(info.value.attributes.kind.type == 'Directory')
+  else if (
+    info.error.payload.cause instanceof RemoteRpcError &&
+    (info.error.payload.cause.code === ErrorCode.FILE_NOT_FOUND ||
+      info.error.payload.cause.code === ErrorCode.CONTENT_ROOT_NOT_FOUND)
+  ) {
+    return Ok(false)
+  } else {
+    return info
+  }
+}
+
+/**
+ * Return a name for a file which does not collide with existing files in `path`.
+ *
+ * First choice is `suggestedName`, and then try to apply a numeric suffix to stem.
+ */
+export async function pickUniqueName(
+  rpc: LanguageServer,
+  path: Path,
+  suggestedName: string,
+): Promise<Result<string>> {
+  const files = await rpc.listFiles(path)
+  if (!files.ok) return files
+  const existingNames = new Set(files.value.paths.map((path) => path.name))
+  const { stem, extension = '' } = splitFilename(suggestedName)
+  let candidate = suggestedName
+  let num = 1
+  while (existingNames.has(candidate)) {
+    candidate = `${stem}_${num}.${extension}`
+    num += 1
+  }
+  return Ok(candidate)
+}
+
 // === Constants ===
 
 const DATA_DIR_NAME = 'data'
@@ -100,9 +158,10 @@ export class Uploader {
     ) {
       return Ok({ source: 'FileSystemRoot', name: this.file.path })
     }
-    const dataDirExists = await this.ensureDataDirExists()
+    const dataDirPath = { rootId: this.projectRootId, segments: [DATA_DIR_NAME] }
+    const dataDirExists = await ensureDirExists(this.rpc, dataDirPath)
     if (!dataDirExists.ok) return dataDirExists
-    const name = await this.pickUniqueName(this.file.name)
+    const name = await pickUniqueName(this.rpc, dataDirPath, this.file.name)
     if (!name.ok) return name
     this.awareness.addOrUpdateUpload(name.value, {
       sizePercentage: 0,
@@ -154,54 +213,6 @@ export class Uploader {
       return Ok()
     }
   }
-
-  private dataDirPath(): Path {
-    return { rootId: this.projectRootId, segments: [DATA_DIR_NAME] }
-  }
-
-  private async ensureDataDirExists() {
-    const exists = await this.dataDirExists()
-    if (!exists.ok) return exists
-    if (exists.value) return Ok()
-    return await withContext(
-      () => 'When creating directory for uploaded file',
-      async () => {
-        return await this.rpc.createFile({
-          type: 'Directory',
-          name: DATA_DIR_NAME,
-          path: { rootId: this.projectRootId, segments: [] },
-        })
-      },
-    )
-  }
-
-  private async dataDirExists(): Promise<Result<boolean>> {
-    const info = await this.rpc.fileInfo(this.dataDirPath())
-    if (info.ok) return Ok(info.value.attributes.kind.type == 'Directory')
-    else if (
-      info.error.payload.cause instanceof RemoteRpcError &&
-      (info.error.payload.cause.code === ErrorCode.FILE_NOT_FOUND ||
-        info.error.payload.cause.code === ErrorCode.CONTENT_ROOT_NOT_FOUND)
-    ) {
-      return Ok(false)
-    } else {
-      return info
-    }
-  }
-
-  private async pickUniqueName(suggestedName: string): Promise<Result<string>> {
-    const files = await this.rpc.listFiles(this.dataDirPath())
-    if (!files.ok) return files
-    const existingNames = new Set(files.value.paths.map((path) => path.name))
-    const { stem, extension = '' } = splitFilename(suggestedName)
-    let candidate = suggestedName
-    let num = 1
-    while (existingNames.has(candidate)) {
-      candidate = `${stem}_${num}.${extension}`
-      num += 1
-    }
-    return Ok(candidate)
-  }
 }
 
 /** Split filename into stem and (optional) extension. */
diff --git a/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue b/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
index 2b33ae05f2dc..a93241b8a585 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
+++ b/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
@@ -54,6 +54,7 @@ defineExpose({
     const range = editorView.state.selection.ranges[0]!
     editorView.dispatch({
       changes: { from: range.from, to: range.to, insert: text },
+      selection: { anchor: range.from + text.length },
     })
   },
 })

From 31f720ec06e2eceb1ae29cb066de7961b27f0a9a Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Fri, 8 Nov 2024 16:33:21 +0100
Subject: [PATCH 04/15] Refactored common parts of uploading files in graph and
 images in docpanel

---
 .../components/DocumentationEditor.vue        |  19 +--
 .../project-view/components/GraphEditor.vue   |  10 +-
 .../components/GraphEditor/upload.ts          | 138 ++++------------
 .../src/project-view/stores/project/index.ts  |  38 +----
 .../src/project-view/stores/projectFiles.ts   | 148 ++++++++++++++++++
 5 files changed, 197 insertions(+), 156 deletions(-)
 create mode 100644 app/gui/src/project-view/stores/projectFiles.ts

diff --git a/app/gui/src/project-view/components/DocumentationEditor.vue b/app/gui/src/project-view/components/DocumentationEditor.vue
index a885a8817ce3..1f9a22ce1c77 100644
--- a/app/gui/src/project-view/components/DocumentationEditor.vue
+++ b/app/gui/src/project-view/components/DocumentationEditor.vue
@@ -6,13 +6,13 @@ import { fetcherUrlTransformer } from '@/components/MarkdownEditor/imageUrlTrans
 import WithFullscreenMode from '@/components/WithFullscreenMode.vue'
 import { useGraphStore } from '@/stores/graph'
 import { useProjectStore } from '@/stores/project'
+import { ProjectFiles, useProjectFiles } from '@/stores/projectFiles'
 import type { ToValue } from '@/util/reactivity'
 import { useToast } from '@/util/toast'
 import { ComponentInstance, ref, toRef, toValue, watch } from 'vue'
 import type { Path } from 'ydoc-shared/languageServerTypes'
 import { Err, Ok, mapOk, withContext, type Result } from 'ydoc-shared/util/data/result'
 import * as Y from 'yjs'
-import { pickUniqueName } from './GraphEditor/upload'
 
 const { yText } = defineProps<{
   yText: Y.Text
@@ -28,14 +28,16 @@ const graphStore = useGraphStore()
 const projectStore = useProjectStore()
 const { transformImageUrl, uploadImage } = useDocumentationImages(
   toRef(graphStore, 'modulePath'),
-  // TODO: is this needed?
-  projectStore.readFileBinary,
+  useProjectFiles(projectStore),
 )
 const uploadErrorToast = useToast.error()
 
 function useDocumentationImages(
   modulePath: ToValue<Path | undefined>,
-  readFileBinary: (path: Path) => Promise<Result<Blob>>,
+  projectFiles: Pick<
+    ProjectFiles,
+    'projectRootId' | 'readFileBinary' | 'writeFileBinary' | 'pickUniqueName'
+  >,
 ) {
   function urlToPath(url: string): Result<Path> | undefined {
     const modulePathValue = toValue(modulePath)
@@ -76,14 +78,14 @@ function useDocumentationImages(
         () => `Loading documentation image (${pathDebugRepr(path)})`,
         () => {
           const uploaded = uploadedImages.get(pathUniqueId(path))
-          return uploaded?.then((blob) => Ok(blob)) ?? readFileBinary(path)
+          return uploaded?.then((blob) => Ok(blob)) ?? projectFiles.readFileBinary(path)
         },
       )
     },
   )
 
   async function uploadImage(name: string, blobPromise: Promise<Blob>) {
-    const rootId = await projectStore.projectRootId
+    const rootId = await projectFiles.projectRootId
     if (!rootId) {
       uploadErrorToast.show('Cannot upload image: unknown project file tree root.')
       return
@@ -92,8 +94,7 @@ function useDocumentationImages(
       console.error('Tried to upload image while mardown editor is still not loaded')
       return
     }
-    const filename = await pickUniqueName(
-      projectStore.lsRpcConnection,
+    const filename = await projectFiles.pickUniqueName(
       {
         rootId,
         segments: ['images'],
@@ -110,7 +111,7 @@ function useDocumentationImages(
     uploadedImages.set(id, blobPromise)
     try {
       const blob = await blobPromise
-      const uploadResult = await projectStore.writeFileBinary(path, blob)
+      const uploadResult = await projectFiles.writeFileBinary(path, blob)
       if (!uploadResult.ok)
         uploadErrorToast.reportError(uploadResult.error, 'Failed to upload image')
     } finally {
diff --git a/app/gui/src/project-view/components/GraphEditor.vue b/app/gui/src/project-view/components/GraphEditor.vue
index 9e76ecec4b20..0495d360ffbd 100644
--- a/app/gui/src/project-view/components/GraphEditor.vue
+++ b/app/gui/src/project-view/components/GraphEditor.vue
@@ -662,11 +662,6 @@ async function handleFileDrop(event: DragEvent) {
   const MULTIPLE_FILES_GAP = 50
 
   if (!event.dataTransfer?.items) return
-  const projectRootId = await projectStore.projectRootId
-  if (projectRootId == null) {
-    toasts.userActionFailed.show(`Unable to upload file(s): Could not identify project root.`)
-    return
-  }
   ;[...event.dataTransfer.items].forEach(async (item, index) => {
     if (item.kind === 'file') {
       const file = item.getAsFile()
@@ -675,10 +670,7 @@ async function handleFileDrop(event: DragEvent) {
       const offset = new Vec2(0, index * -MULTIPLE_FILES_GAP)
       const pos = graphNavigator.clientToScenePos(clientPos).add(offset)
       const uploader = Uploader.Create(
-        projectStore.lsRpcConnection,
-        projectStore.dataConnection,
-        projectRootId,
-        projectStore.awareness,
+        projectStore,
         file,
         pos,
         projectStore.isOnLocalBackend,
diff --git a/app/gui/src/project-view/components/GraphEditor/upload.ts b/app/gui/src/project-view/components/GraphEditor/upload.ts
index 044b7bddc58c..7a7458be2d80 100644
--- a/app/gui/src/project-view/components/GraphEditor/upload.ts
+++ b/app/gui/src/project-view/components/GraphEditor/upload.ts
@@ -1,73 +1,14 @@
 import { Awareness } from '@/stores/awareness'
+import { ProjectFiles, useProjectFiles } from '@/stores/projectFiles'
 import { Vec2 } from '@/util/data/vec2'
 import type { DataServer } from '@/util/net/dataServer'
 import { Keccak, sha3_224 as SHA3 } from '@noble/hashes/sha3'
 import type { Hash } from '@noble/hashes/utils'
-import { bytesToHex } from '@noble/hashes/utils'
 import { markRaw, toRaw } from 'vue'
 import { escapeTextLiteral } from 'ydoc-shared/ast/text'
 import type { LanguageServer } from 'ydoc-shared/languageServer'
-import { ErrorCode, RemoteRpcError } from 'ydoc-shared/languageServer'
-import type { Path, StackItem, Uuid } from 'ydoc-shared/languageServerTypes'
-import { Err, Ok, withContext, type Result } from 'ydoc-shared/util/data/result'
-
-/** Check if directory exists and try to create one if missing. */
-export async function ensureDirExists(rpc: LanguageServer, path: Path) {
-  const exists = await dirExists(rpc, path)
-  if (!exists.ok) return exists
-  if (exists.value) return Ok()
-
-  const name = path.segments.at(-1)
-  if (name == null) return Err('Cannot create context root')
-
-  return await withContext(
-    () => 'When creating directory for uploaded file',
-    async () => {
-      return await rpc.createFile({
-        type: 'Directory',
-        name,
-        path: { rootId: path.rootId, segments: path.segments.slice(0, -1) },
-      })
-    },
-  )
-}
-
-async function dirExists(rpc: LanguageServer, path: Path): Promise<Result<boolean>> {
-  const info = await rpc.fileInfo(path)
-  if (info.ok) return Ok(info.value.attributes.kind.type == 'Directory')
-  else if (
-    info.error.payload.cause instanceof RemoteRpcError &&
-    (info.error.payload.cause.code === ErrorCode.FILE_NOT_FOUND ||
-      info.error.payload.cause.code === ErrorCode.CONTENT_ROOT_NOT_FOUND)
-  ) {
-    return Ok(false)
-  } else {
-    return info
-  }
-}
-
-/**
- * Return a name for a file which does not collide with existing files in `path`.
- *
- * First choice is `suggestedName`, and then try to apply a numeric suffix to stem.
- */
-export async function pickUniqueName(
-  rpc: LanguageServer,
-  path: Path,
-  suggestedName: string,
-): Promise<Result<string>> {
-  const files = await rpc.listFiles(path)
-  if (!files.ok) return files
-  const existingNames = new Set(files.value.paths.map((path) => path.name))
-  const { stem, extension = '' } = splitFilename(suggestedName)
-  let candidate = suggestedName
-  let num = 1
-  while (existingNames.has(candidate)) {
-    candidate = `${stem}_${num}.${extension}`
-    num += 1
-  }
-  return Ok(candidate)
-}
+import type { Path, StackItem } from 'ydoc-shared/languageServerTypes'
+import { Err, Ok, type Result } from 'ydoc-shared/util/data/result'
 
 // === Constants ===
 
@@ -105,13 +46,16 @@ export class Uploader {
   private checksum: Hash<Keccak>
   private uploadedBytes: bigint
   private stackItem: StackItem
+  private awareness: Awareness
+  private projectFiles: ProjectFiles
 
   private constructor(
-    private rpc: LanguageServer,
-    private binary: DataServer,
-    private awareness: Awareness,
+    projectStore: {
+      lsRpcConnection: LanguageServer
+      dataConnection: DataServer
+      awareness: Awareness
+    },
     private file: File,
-    private projectRootId: Uuid,
     private position: Vec2,
     private isOnLocalBackend: boolean,
     private disableDirectRead: boolean,
@@ -120,14 +64,17 @@ export class Uploader {
     this.checksum = SHA3.create()
     this.uploadedBytes = BigInt(0)
     this.stackItem = markRaw(toRaw(stackItem))
+    this.awareness = projectStore.awareness
+    this.projectFiles = useProjectFiles(projectStore)
   }
 
   /** Constructor */
   static Create(
-    rpc: LanguageServer,
-    binary: DataServer,
-    projectRootId: Uuid,
-    awareness: Awareness,
+    projectStore: {
+      lsRpcConnection: LanguageServer
+      dataConnection: DataServer
+      awareness: Awareness
+    },
     file: File,
     position: Vec2,
     isOnLocalBackend: boolean,
@@ -135,11 +82,8 @@ export class Uploader {
     stackItem: StackItem,
   ): Uploader {
     return new Uploader(
-      rpc,
-      binary,
-      awareness,
+      projectStore,
       file,
-      projectRootId,
       position,
       isOnLocalBackend,
       disableDirectRead,
@@ -158,21 +102,29 @@ export class Uploader {
     ) {
       return Ok({ source: 'FileSystemRoot', name: this.file.path })
     }
-    const dataDirPath = { rootId: this.projectRootId, segments: [DATA_DIR_NAME] }
-    const dataDirExists = await ensureDirExists(this.rpc, dataDirPath)
+    const rootId = await this.projectFiles.projectRootId
+    if (rootId == null) return Err('Could not identify project root.')
+    const dataDirPath = { rootId, segments: [DATA_DIR_NAME] }
+    const dataDirExists = await this.projectFiles.ensureDirExists(dataDirPath)
     if (!dataDirExists.ok) return dataDirExists
-    const name = await pickUniqueName(this.rpc, dataDirPath, this.file.name)
+    const name = await this.projectFiles.pickUniqueName(dataDirPath, this.file.name)
     if (!name.ok) return name
     this.awareness.addOrUpdateUpload(name.value, {
       sizePercentage: 0,
       position: this.position,
       stackItem: this.stackItem,
     })
-    const remotePath: Path = { rootId: this.projectRootId, segments: [DATA_DIR_NAME, name.value] }
+    const remotePath: Path = { rootId, segments: [DATA_DIR_NAME, name.value] }
     const cleanup = this.cleanup.bind(this, name.value)
     const writableStream = new WritableStream<Uint8Array>({
       write: async (chunk: Uint8Array) => {
-        await this.binary.writeBytes(remotePath, this.uploadedBytes, false, chunk)
+        const result = await this.projectFiles.writeBytes(
+          remotePath,
+          this.uploadedBytes,
+          false,
+          chunk,
+        )
+        if (!result.ok) throw result.error
         this.checksum.update(chunk)
         this.uploadedBytes += BigInt(chunk.length)
         const bytes = Number(this.uploadedBytes)
@@ -186,13 +138,13 @@ export class Uploader {
       close: cleanup,
       abort: async (reason: string) => {
         cleanup()
-        await this.rpc.deleteFile(remotePath)
+        await this.projectFiles.deleteFile(remotePath)
         throw new Error(`Uploading process aborted. ${reason}`)
       },
     })
     // Disabled until https://github.com/enso-org/enso/issues/6691 is fixed.
     // Plus, handle the error here, as it should be displayed to the user.
-    // uploader.assertChecksum(remotePath)
+    // this.projectFiles.assertChecksum(remotePath)
     await this.file.stream().pipeTo(writableStream)
     return Ok({ source: 'Project', name: name.value })
   }
@@ -200,28 +152,4 @@ export class Uploader {
   private cleanup(name: string) {
     this.awareness.removeUpload(name)
   }
-
-  private async assertChecksum(path: Path): Promise<Result<void>> {
-    const engineChecksum = await this.rpc.fileChecksum(path)
-    if (!engineChecksum.ok) return engineChecksum
-    const hexChecksum = bytesToHex(this.checksum.digest())
-    if (hexChecksum != engineChecksum.value.checksum) {
-      return Err(
-        `Uploading file failed, checksum does not match. ${hexChecksum} != ${engineChecksum.value.checksum}`,
-      )
-    } else {
-      return Ok()
-    }
-  }
-}
-
-/** Split filename into stem and (optional) extension. */
-function splitFilename(fileName: string): { stem: string; extension?: string } {
-  const dotIndex = fileName.lastIndexOf('.')
-  if (dotIndex !== -1 && dotIndex !== 0) {
-    const stem = fileName.substring(0, dotIndex)
-    const extension = fileName.substring(dotIndex + 1)
-    return { stem, extension }
-  }
-  return { stem: fileName }
 }
diff --git a/app/gui/src/project-view/stores/project/index.ts b/app/gui/src/project-view/stores/project/index.ts
index c3c490b975e8..28c0c312118c 100644
--- a/app/gui/src/project-view/stores/project/index.ts
+++ b/app/gui/src/project-view/stores/project/index.ts
@@ -30,13 +30,9 @@ import {
   type WatchSource,
   type WritableComputedRef,
 } from 'vue'
-import {
-  Error as DataError,
-  OutboundPayload,
-  VisualizationUpdate,
-} from 'ydoc-shared/binaryProtocol'
+import { OutboundPayload, VisualizationUpdate } from 'ydoc-shared/binaryProtocol'
 import { LanguageServer } from 'ydoc-shared/languageServer'
-import type { Diagnostic, ExpressionId, MethodPointer, Path } from 'ydoc-shared/languageServerTypes'
+import type { Diagnostic, ExpressionId, MethodPointer } from 'ydoc-shared/languageServerTypes'
 import { type AbortScope } from 'ydoc-shared/util/net'
 import {
   DistributedProject,
@@ -129,7 +125,9 @@ export const { provideFn: provideProjectStore, injectFn: useProjectStore } = cre
     const clientId = random.uuidv4() as Uuid
     const lsUrls = resolveLsUrl(config.value)
     const lsRpcConnection = createLsRpcConnection(clientId, lsUrls.rpcUrl, abort)
-    const contentRoots = lsRpcConnection.contentRoots
+    const projectRootId = lsRpcConnection.contentRoots.then(
+      (roots) => roots.find((root) => root.type === 'Project')?.id,
+    )
 
     const dataConnection = initializeDataConnection(clientId, lsUrls.dataUrl, abort)
     const rpcUrl = new URL(lsUrls.rpcUrl)
@@ -375,30 +373,6 @@ export const { provideFn: provideProjectStore, injectFn: useProjectStore } = cre
       }
     })
 
-    const projectRootId = contentRoots.then(
-      (roots) => roots.find((root) => root.type === 'Project')?.id,
-    )
-
-    async function readFileBinary(path: Path): Promise<Result<Blob>> {
-      const result = await dataConnection.readFile(path)
-      if (result instanceof DataError) {
-        return Err(result.message() ?? 'Failed to read file.')
-      }
-      const contents = result.contentsArray()
-      if (contents == null) {
-        return Err('No file contents received.')
-      }
-      return Ok(new Blob([contents]))
-    }
-
-    async function writeFileBinary(path: Path, content: Blob): Promise<Result> {
-      const result = await dataConnection.writeFile(path, await content.arrayBuffer())
-      if (result instanceof DataError) {
-        return Err(result.message() ?? 'Failed to write file.')
-      }
-      return Ok()
-    }
-
     return proxyRefs({
       setObservedFileName(name: string) {
         observedFileName.value = name
@@ -422,8 +396,6 @@ export const { provideFn: provideProjectStore, injectFn: useProjectStore } = cre
       computedValueRegistry: markRaw(computedValueRegistry),
       lsRpcConnection: markRaw(lsRpcConnection),
       dataConnection: markRaw(dataConnection),
-      readFileBinary,
-      writeFileBinary,
       useVisualizationData,
       isRecordingEnabled,
       stopCapturingUndo,
diff --git a/app/gui/src/project-view/stores/projectFiles.ts b/app/gui/src/project-view/stores/projectFiles.ts
new file mode 100644
index 000000000000..0c1e1581e3b1
--- /dev/null
+++ b/app/gui/src/project-view/stores/projectFiles.ts
@@ -0,0 +1,148 @@
+import { DataServer } from '@/util/net/dataServer'
+import { bytesToHex, Hash } from '@noble/hashes/utils'
+import { Error as DataError } from 'ydoc-shared/binaryProtocol'
+import { ErrorCode, LanguageServer, RemoteRpcError } from 'ydoc-shared/languageServer'
+import { Path, Uuid } from 'ydoc-shared/languageServerTypes'
+import { Err, Ok, Result, withContext } from 'ydoc-shared/util/data/result'
+
+export type ProjectFiles = ReturnType<typeof useProjectFiles>
+
+/**
+ * A composable with project files operations.
+ */
+export function useProjectFiles(projectStore: {
+  projectRootId: Promise<Uuid | undefined>
+  lsRpcConnection: LanguageServer
+  dataConnection: DataServer
+}) {
+  const { projectRootId, lsRpcConnection: lsRpc, dataConnection } = projectStore
+
+  async function readFileBinary(path: Path): Promise<Result<Blob>> {
+    const result = await dataConnection.readFile(path)
+    if (result instanceof DataError) {
+      return Err(result.message() ?? 'Failed to read file.')
+    }
+    const contents = result.contentsArray()
+    if (contents == null) {
+      return Err('No file contents received.')
+    }
+    return Ok(new Blob([contents]))
+  }
+
+  async function writeFileBinary(path: Path, content: Blob): Promise<Result> {
+    const result = await dataConnection.writeFile(path, await content.arrayBuffer())
+    if (result instanceof DataError) {
+      return Err(result.message() ?? 'Failed to write file.')
+    }
+    return Ok()
+  }
+
+  async function writeBytes(
+    path: Path,
+    offset: bigint,
+    overwriteExisting: boolean,
+    contents: string | ArrayBuffer | Uint8Array,
+  ): Promise<Result> {
+    const result = await dataConnection.writeBytes(path, offset, overwriteExisting, contents)
+    if (result instanceof DataError) {
+      return Err(result.message() ?? 'Failed to write bytes.')
+    }
+    return Ok()
+  }
+
+  async function deleteFile(path: Path) {
+    return lsRpc.deleteFile(path)
+  }
+
+  /** Check if directory exists and try to create one if missing. */
+  async function ensureDirExists(path: Path) {
+    const exists = await dirExists(path)
+    if (!exists.ok) return exists
+    if (exists.value) return Ok()
+
+    const name = path.segments.at(-1)
+    if (name == null) return Err('Cannot create context root')
+
+    return await withContext(
+      () => 'When creating directory for uploaded file',
+      async () => {
+        return await lsRpc.createFile({
+          type: 'Directory',
+          name,
+          path: { rootId: path.rootId, segments: path.segments.slice(0, -1) },
+        })
+      },
+    )
+  }
+
+  async function dirExists(path: Path): Promise<Result<boolean>> {
+    const info = await lsRpc.fileInfo(path)
+    if (info.ok) return Ok(info.value.attributes.kind.type == 'Directory')
+    else if (
+      info.error.payload.cause instanceof RemoteRpcError &&
+      (info.error.payload.cause.code === ErrorCode.FILE_NOT_FOUND ||
+        info.error.payload.cause.code === ErrorCode.CONTENT_ROOT_NOT_FOUND)
+    ) {
+      return Ok(false)
+    } else {
+      return info
+    }
+  }
+
+  /**
+   * Return a name for a file which does not collide with existing files in `path`.
+   *
+   * First choice is `suggestedName`, and then try to apply a numeric suffix to stem.
+   */
+  async function pickUniqueName(path: Path, suggestedName: string): Promise<Result<string>> {
+    const files = await lsRpc.listFiles(path)
+    if (!files.ok) return files
+    const existingNames = new Set(files.value.paths.map((path) => path.name))
+    const { stem, extension = '' } = splitFilename(suggestedName)
+    let candidate = suggestedName
+    let num = 1
+    while (existingNames.has(candidate)) {
+      candidate = `${stem}_${num}.${extension}`
+      num += 1
+    }
+    return Ok(candidate)
+  }
+
+  async function assertChecksum<T extends Hash<T>>(
+    path: Path,
+    checksum: Hash<T>,
+  ): Promise<Result<void>> {
+    const engineChecksum = await lsRpc.fileChecksum(path)
+    if (!engineChecksum.ok) return engineChecksum
+    const hexChecksum = bytesToHex(checksum.digest())
+    if (hexChecksum != engineChecksum.value.checksum) {
+      return Err(
+        `Uploading file failed, checksum does not match. ${hexChecksum} != ${engineChecksum.value.checksum}`,
+      )
+    } else {
+      return Ok()
+    }
+  }
+
+  return {
+    projectRootId,
+    readFileBinary,
+    writeFileBinary,
+    writeBytes,
+    deleteFile,
+    ensureDirExists,
+    pickUniqueName,
+    assertChecksum,
+  }
+}
+
+/** Split filename into stem and (optional) extension. */
+function splitFilename(fileName: string): { stem: string; extension?: string } {
+  const dotIndex = fileName.lastIndexOf('.')
+  if (dotIndex !== -1 && dotIndex !== 0) {
+    const stem = fileName.substring(0, dotIndex)
+    const extension = fileName.substring(dotIndex + 1)
+    return { stem, extension }
+  }
+  return { stem: fileName }
+}

From 50c93bacbec46abcc69bd0d08a174b2c2e722de4 Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Tue, 12 Nov 2024 16:42:17 +0100
Subject: [PATCH 05/15] Dropping image

---
 .../components/DocumentationEditor.vue        | 41 +++++++++++++++++--
 .../components/GraphEditor/upload.ts          |  4 +-
 .../components/MarkdownEditor.vue             |  4 ++
 .../MarkdownEditor/MarkdownEditorImpl.vue     |  8 ++++
 .../MarkdownEditor/markdown/decoration.ts     |  5 ++-
 5 files changed, 56 insertions(+), 6 deletions(-)

diff --git a/app/gui/src/project-view/components/DocumentationEditor.vue b/app/gui/src/project-view/components/DocumentationEditor.vue
index 1f9a22ce1c77..8b7fe4e3e33c 100644
--- a/app/gui/src/project-view/components/DocumentationEditor.vue
+++ b/app/gui/src/project-view/components/DocumentationEditor.vue
@@ -7,6 +7,7 @@ import WithFullscreenMode from '@/components/WithFullscreenMode.vue'
 import { useGraphStore } from '@/stores/graph'
 import { useProjectStore } from '@/stores/project'
 import { ProjectFiles, useProjectFiles } from '@/stores/projectFiles'
+import { Vec2 } from '@/util/data/vec2'
 import type { ToValue } from '@/util/reactivity'
 import { useToast } from '@/util/toast'
 import { ComponentInstance, ref, toRef, toValue, watch } from 'vue'
@@ -32,6 +33,8 @@ const { transformImageUrl, uploadImage } = useDocumentationImages(
 )
 const uploadErrorToast = useToast.error()
 
+type UploadedImagePosition = { type: 'selection' } | { type: 'coords'; coords: Vec2 }
+
 function useDocumentationImages(
   modulePath: ToValue<Path | undefined>,
   projectFiles: Pick<
@@ -46,7 +49,7 @@ function useDocumentationImages(
     }
     const appliedUrl = new URL(url, `file:///${modulePathValue.segments.join('/')}`)
     if (appliedUrl.protocol === 'file:') {
-      const segments = appliedUrl.pathname.split('/').slice(1)
+      const segments = decodeURI(appliedUrl.pathname).split('/').slice(1)
       return Ok({ rootId: modulePathValue.rootId, segments })
     } else {
       // Not a relative URL, custom fetching not needed.
@@ -84,7 +87,11 @@ function useDocumentationImages(
     },
   )
 
-  async function uploadImage(name: string, blobPromise: Promise<Blob>) {
+  async function uploadImage(
+    name: string,
+    blobPromise: Promise<Blob>,
+    position: UploadedImagePosition = { type: 'selection' },
+  ) {
     const rootId = await projectFiles.projectRootId
     if (!rootId) {
       uploadErrorToast.show('Cannot upload image: unknown project file tree root.')
@@ -105,7 +112,14 @@ function useDocumentationImages(
       uploadErrorToast.reportError(filename.error)
       return
     }
-    markdownEditor.value.putText(`![Image](/images/${filename.value})`)
+    const insertedLink = `\n![Image](/images/${encodeURI(filename.value)})\n`
+    switch (position.type) {
+      case 'selection':
+        markdownEditor.value.putText(insertedLink)
+        break
+      case 'coords':
+        markdownEditor.value.putTextAtCoord(insertedLink, position.coords)
+    }
     const path: Path = { rootId, segments: ['images', filename.value] }
     const id = pathUniqueId(path)
     uploadedImages.set(id, blobPromise)
@@ -142,6 +156,20 @@ const supportedImageTypes: Record<string, { extension: string }> = {
   // Question: do we want to have BMP and ICO here?
 }
 
+async function handleFileDrop(event: DragEvent) {
+  console.log('HANDLE FILE DROP')
+  if (!event.dataTransfer?.items) return
+  for (const item of event.dataTransfer.items) {
+    if (item.kind !== 'file' || !(item.type in supportedImageTypes)) return
+    const file = item.getAsFile()
+    if (!file) return
+    const clientPos = new Vec2(event.clientX, event.clientY)
+    event.stopPropagation()
+    event.preventDefault()
+    await uploadImage(file.name, Promise.resolve(file), { type: 'coords', coords: clientPos })
+  }
+}
+
 const handler = documentationEditorBindings.handler({
   pasteImage: () => {
     window.navigator.clipboard.read().then(async (items) => {
@@ -173,7 +201,12 @@ const handler = documentationEditorBindings.handler({
       <div ref="toolbarElement" class="toolbar">
         <FullscreenButton v-model="fullscreen" />
       </div>
-      <div class="scrollArea" @keydown="handler">
+      <div
+        class="scrollArea"
+        @keydown="handler"
+        @dragover.prevent
+        @drop.prevent="handleFileDrop($event)"
+      >
         <MarkdownEditor
           ref="markdownEditor"
           :yText="yText"
diff --git a/app/gui/src/project-view/components/GraphEditor/upload.ts b/app/gui/src/project-view/components/GraphEditor/upload.ts
index 7a7458be2d80..be9e90d4196a 100644
--- a/app/gui/src/project-view/components/GraphEditor/upload.ts
+++ b/app/gui/src/project-view/components/GraphEditor/upload.ts
@@ -7,7 +7,7 @@ import type { Hash } from '@noble/hashes/utils'
 import { markRaw, toRaw } from 'vue'
 import { escapeTextLiteral } from 'ydoc-shared/ast/text'
 import type { LanguageServer } from 'ydoc-shared/languageServer'
-import type { Path, StackItem } from 'ydoc-shared/languageServerTypes'
+import type { Path, StackItem, Uuid } from 'ydoc-shared/languageServerTypes'
 import { Err, Ok, type Result } from 'ydoc-shared/util/data/result'
 
 // === Constants ===
@@ -51,6 +51,7 @@ export class Uploader {
 
   private constructor(
     projectStore: {
+      projectRootId: Promise<Uuid | undefined>
       lsRpcConnection: LanguageServer
       dataConnection: DataServer
       awareness: Awareness
@@ -71,6 +72,7 @@ export class Uploader {
   /** Constructor */
   static Create(
     projectStore: {
+      projectRootId: Promise<Uuid | undefined>
       lsRpcConnection: LanguageServer
       dataConnection: DataServer
       awareness: Awareness
diff --git a/app/gui/src/project-view/components/MarkdownEditor.vue b/app/gui/src/project-view/components/MarkdownEditor.vue
index da22315816c8..f0c4435dc7f0 100644
--- a/app/gui/src/project-view/components/MarkdownEditor.vue
+++ b/app/gui/src/project-view/components/MarkdownEditor.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import type { UrlTransformer } from '@/components/MarkdownEditor/imageUrlTransformer'
+import { Vec2 } from '@/util/data/vec2'
 import { ComponentInstance, computed, defineAsyncComponent, ref } from 'vue'
 import * as Y from 'yjs'
 
@@ -20,6 +21,9 @@ defineExpose({
   putText: (text: string) => {
     inner.value?.putText(text)
   },
+  putTextAtCoord: (text: string, coords: Vec2) => {
+    inner.value?.putTextAtCoords(text, coords)
+  },
 })
 </script>
 
diff --git a/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue b/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
index a93241b8a585..b461f27686cb 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
+++ b/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
@@ -7,6 +7,7 @@ import {
 } from '@/components/MarkdownEditor/imageUrlTransformer'
 import { ensoMarkdown } from '@/components/MarkdownEditor/markdown'
 import VueComponentHost from '@/components/VueComponentHost.vue'
+import { Vec2 } from '@/util/data/vec2'
 import { EditorState } from '@codemirror/state'
 import { EditorView } from '@codemirror/view'
 import { minimalSetup } from 'codemirror'
@@ -57,6 +58,13 @@ defineExpose({
       selection: { anchor: range.from + text.length },
     })
   },
+  putTextAtCoords: (text: string, coords: Vec2) => {
+    const pos = editorView.posAtCoords(coords, false)
+    editorView.dispatch({
+      changes: { from: pos, to: pos, insert: text },
+      selection: { anchor: pos + text.length },
+    })
+  },
 })
 </script>
 
diff --git a/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts b/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts
index bce93559a1f6..9c1f5b98fb34 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts
+++ b/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts
@@ -150,10 +150,13 @@ function parseLinkLike(node: SyntaxNode, doc: Text) {
   const urlNode = urlOpen.nextSibling
   // If the URL is empty, this will be the closing 'LinkMark'.
   if (urlNode?.name !== 'URL') return
+  const url = doc.sliceString(urlNode.from, urlNode.to)
+  // See https://spec.commonmark.org/0.31.2/#link-destination
+  const withTriangleBrackets = url.startsWith('<') && url.endsWith('>')
   return {
     textFrom: textOpen.to,
     textTo: textClose.from,
-    url: doc.sliceString(urlNode.from, urlNode.to),
+    url: withTriangleBrackets ? url.slice(1, -1) : url,
   }
 }
 

From 7d61d43d829c6a74258fec0051b23a8ec8f08749 Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Wed, 13 Nov 2024 11:35:54 +0100
Subject: [PATCH 06/15] Some missing docs

---
 .../MarkdownEditor/imageUrlTransformer.ts           | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/app/gui/src/project-view/components/MarkdownEditor/imageUrlTransformer.ts b/app/gui/src/project-view/components/MarkdownEditor/imageUrlTransformer.ts
index b3859ab168dc..fd31924a56b8 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/imageUrlTransformer.ts
+++ b/app/gui/src/project-view/components/MarkdownEditor/imageUrlTransformer.ts
@@ -3,6 +3,12 @@ import type { ToValue } from '@/util/reactivity'
 import { toValue } from 'vue'
 import { mapOk, Ok, type Result } from 'ydoc-shared/util/data/result'
 
+/**
+ * A transformed URL.
+ *
+ * Once the returned URL is not used anymore, `dispose` callback is called allowing release
+ * any resource under that URL.
+ */
 export type TransformUrlResult = Result<{ url: string; dispose?: () => void }>
 export type UrlTransformer = (url: string) => Promise<TransformUrlResult>
 
@@ -26,7 +32,12 @@ export interface ResourceInfo<T> {
 export type ResourceLocator<T> = (url: Url) => Promise<Result<ResourceInfo<T>> | undefined>
 export type ResourceFetcher<T> = (locator: T) => Promise<Result<Blob>>
 
-/** TODO: Add docs */
+/**
+ * Create {@link UrlTransformer} which fetches and caches the image. Returns a URL created
+ * with `URL.createObjectURL`.
+ *
+ * May be used in cases, when the image is not available for browser through HTTP protocol.
+ */
 export function fetcherUrlTransformer<ResourceLocation>(
   locateResource: ResourceLocator<ResourceLocation>,
   fetchResource: ResourceFetcher<ResourceLocation>,

From 5f383ef6ed04a76b01c3b7fa717a6c01e4de21bd Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Wed, 13 Nov 2024 14:41:55 +0100
Subject: [PATCH 07/15] Make images being uploaded a bit transparent

---
 .../components/DocumentationEditor.vue        | 21 +++++++++++++------
 .../MarkdownEditor/DocumentationImage.vue     |  7 ++++++-
 .../MarkdownEditor/MarkdownEditorImpl.vue     |  4 ++++
 .../MarkdownEditor/imageUrlTransformer.ts     | 15 ++++++++++---
 4 files changed, 37 insertions(+), 10 deletions(-)

diff --git a/app/gui/src/project-view/components/DocumentationEditor.vue b/app/gui/src/project-view/components/DocumentationEditor.vue
index 8b7fe4e3e33c..c7e7180bbf34 100644
--- a/app/gui/src/project-view/components/DocumentationEditor.vue
+++ b/app/gui/src/project-view/components/DocumentationEditor.vue
@@ -10,7 +10,7 @@ import { ProjectFiles, useProjectFiles } from '@/stores/projectFiles'
 import { Vec2 } from '@/util/data/vec2'
 import type { ToValue } from '@/util/reactivity'
 import { useToast } from '@/util/toast'
-import { ComponentInstance, ref, toRef, toValue, watch } from 'vue'
+import { ComponentInstance, computed, reactive, ref, toRef, toValue, watch } from 'vue'
 import type { Path } from 'ydoc-shared/languageServerTypes'
 import { Err, Ok, mapOk, withContext, type Result } from 'ydoc-shared/util/data/result'
 import * as Y from 'yjs'
@@ -65,7 +65,7 @@ function useDocumentationImages(
     return pathUniqueId(path)
   }
 
-  const uploadedImages = new Map<string, Promise<Blob>>()
+  const uploadedImages = reactive(new Map<string, Promise<Blob>>())
 
   const transformImageUrl = fetcherUrlTransformer(
     async (url: string) => {
@@ -73,7 +73,15 @@ function useDocumentationImages(
       if (!path) return
       return withContext(
         () => `Locating documentation image (${url})`,
-        () => mapOk(path, (path) => ({ location: path, uniqueId: pathUniqueId(path) })),
+        () =>
+          mapOk(path, (path) => {
+            const id = pathUniqueId(path)
+            return {
+              location: path,
+              uniqueId: id,
+              uploading: computed(() => uploadedImages.has(id)),
+            }
+          }),
       )
     },
     async (path) => {
@@ -112,6 +120,10 @@ function useDocumentationImages(
       uploadErrorToast.reportError(filename.error)
       return
     }
+    const path: Path = { rootId, segments: ['images', filename.value] }
+    const id = pathUniqueId(path)
+    uploadedImages.set(id, blobPromise)
+
     const insertedLink = `\n![Image](/images/${encodeURI(filename.value)})\n`
     switch (position.type) {
       case 'selection':
@@ -120,9 +132,6 @@ function useDocumentationImages(
       case 'coords':
         markdownEditor.value.putTextAtCoord(insertedLink, position.coords)
     }
-    const path: Path = { rootId, segments: ['images', filename.value] }
-    const id = pathUniqueId(path)
-    uploadedImages.set(id, blobPromise)
     try {
       const blob = await blobPromise
       const uploadResult = await projectFiles.writeFileBinary(path, blob)
diff --git a/app/gui/src/project-view/components/MarkdownEditor/DocumentationImage.vue b/app/gui/src/project-view/components/MarkdownEditor/DocumentationImage.vue
index 545fc82325c9..a4f7aeb7d043 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/DocumentationImage.vue
+++ b/app/gui/src/project-view/components/MarkdownEditor/DocumentationImage.vue
@@ -40,5 +40,10 @@ onUnmounted(() => {
 </script>
 
 <template>
-  <img :src="data?.ok ? data.value.url : ''" :alt="alt" :title="title" />
+  <img
+    :src="data?.ok ? data.value.url : ''"
+    :alt="alt"
+    :title="title"
+    :class="{ uploading: data?.ok && data.value.uploading?.value }"
+  />
 </template>
diff --git a/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue b/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
index b461f27686cb..e31d50fa7d7f 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
+++ b/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
@@ -88,6 +88,10 @@ defineExpose({
   overscroll-behavior: none;
 }
 
+:deep(img.uploading) {
+  opacity: 0.5;
+}
+
 .EditorRoot :deep(.cm-editor) {
   position: relative;
   width: 100%;
diff --git a/app/gui/src/project-view/components/MarkdownEditor/imageUrlTransformer.ts b/app/gui/src/project-view/components/MarkdownEditor/imageUrlTransformer.ts
index fd31924a56b8..b2ee3009d7df 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/imageUrlTransformer.ts
+++ b/app/gui/src/project-view/components/MarkdownEditor/imageUrlTransformer.ts
@@ -1,6 +1,6 @@
 import { createContextStore } from '@/providers'
 import type { ToValue } from '@/util/reactivity'
-import { toValue } from 'vue'
+import { Ref, toValue } from 'vue'
 import { mapOk, Ok, type Result } from 'ydoc-shared/util/data/result'
 
 /**
@@ -8,8 +8,15 @@ import { mapOk, Ok, type Result } from 'ydoc-shared/util/data/result'
  *
  * Once the returned URL is not used anymore, `dispose` callback is called allowing release
  * any resource under that URL.
+ *
+ * `uploading` is set to true while the image is being uploaded to its target destination
+ * (as part of pasting image, for example).
  */
-export type TransformUrlResult = Result<{ url: string; dispose?: () => void }>
+export type TransformUrlResult = Result<{
+  url: string
+  dispose?: () => void
+  uploading?: Ref<boolean>
+}>
 export type UrlTransformer = (url: string) => Promise<TransformUrlResult>
 
 export {
@@ -28,6 +35,7 @@ type Url = string
 export interface ResourceInfo<T> {
   location: T
   uniqueId: ResourceId
+  uploading?: Ref<boolean>
 }
 export type ResourceLocator<T> = (url: Url) => Promise<Result<ResourceInfo<T>> | undefined>
 export type ResourceFetcher<T> = (locator: T) => Promise<Result<Blob>>
@@ -59,7 +67,7 @@ export function fetcherUrlTransformer<ResourceLocation>(
     } else if (!resource.ok) {
       return resource
     } else {
-      const { uniqueId, location } = resource.value
+      const { uniqueId, location, uploading } = resource.value
       const result = await (allocatedUrls.get(uniqueId) ?? startFetch(uniqueId, location))
       if (!result.ok) {
         // Changes to external state may allow a future attempt to succeed.
@@ -75,6 +83,7 @@ export function fetcherUrlTransformer<ResourceLocation>(
             allocatedUrls.delete(uniqueId)
           }
         },
+        uploading,
       })
     }
   }

From 3da57c18cee338d810fabe691f217db8ee2a3676 Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Wed, 13 Nov 2024 15:22:15 +0100
Subject: [PATCH 08/15] Self-review

---
 .../project-view/components/DocumentationEditor.vue | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/app/gui/src/project-view/components/DocumentationEditor.vue b/app/gui/src/project-view/components/DocumentationEditor.vue
index c7e7180bbf34..0599c1bf9775 100644
--- a/app/gui/src/project-view/components/DocumentationEditor.vue
+++ b/app/gui/src/project-view/components/DocumentationEditor.vue
@@ -39,7 +39,7 @@ function useDocumentationImages(
   modulePath: ToValue<Path | undefined>,
   projectFiles: Pick<
     ProjectFiles,
-    'projectRootId' | 'readFileBinary' | 'writeFileBinary' | 'pickUniqueName'
+    'projectRootId' | 'readFileBinary' | 'writeFileBinary' | 'pickUniqueName' | 'ensureDirExists'
   >,
 ) {
   function urlToPath(url: string): Result<Path> | undefined {
@@ -49,6 +49,7 @@ function useDocumentationImages(
     }
     const appliedUrl = new URL(url, `file:///${modulePathValue.segments.join('/')}`)
     if (appliedUrl.protocol === 'file:') {
+      // The pathname starts with '/', so we remove "" segment.
       const segments = decodeURI(appliedUrl.pathname).split('/').slice(1)
       return Ok({ rootId: modulePathValue.rootId, segments })
     } else {
@@ -109,13 +110,9 @@ function useDocumentationImages(
       console.error('Tried to upload image while mardown editor is still not loaded')
       return
     }
-    const filename = await projectFiles.pickUniqueName(
-      {
-        rootId,
-        segments: ['images'],
-      },
-      name,
-    )
+    const dirPath = { rootId, segments: ['images'] }
+    await projectFiles.ensureDirExists(dirPath)
+    const filename = await projectFiles.pickUniqueName(dirPath, name)
     if (!filename.ok) {
       uploadErrorToast.reportError(filename.error)
       return

From e34374d097b64a50be0193a0bcc1272e32c6cfdb Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Wed, 13 Nov 2024 15:30:52 +0100
Subject: [PATCH 09/15] CHANGELOG

---
 CHANGELOG.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 682b71ad6033..5f158da82720 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,8 @@
   component.][11452]
 - [New documentation editor provides improved Markdown editing experience, and
   paves the way for new documentation features.][11469]
+- [You can now add images to documentation panel][11547] by pasting them from
+  clipboard or by drag'n'droping image files.
 
 [11151]: https://github.com/enso-org/enso/pull/11151
 [11271]: https://github.com/enso-org/enso/pull/11271
@@ -40,6 +42,7 @@
 [11448]: https://github.com/enso-org/enso/pull/11448
 [11452]: https://github.com/enso-org/enso/pull/11452
 [11469]: https://github.com/enso-org/enso/pull/11469
+[11547]: https://github.com/enso-org/enso/pull/11547
 
 #### Enso Standard Library
 

From beecc39353d4a222a2d2a82bed74406ce0a4db81 Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Thu, 14 Nov 2024 13:54:55 +0100
Subject: [PATCH 10/15] Apply review

---
 CHANGELOG.md                                  |  2 +-
 app/gui/src/project-view/bindings.ts          |  2 +-
 .../components/DocumentationEditor.vue        |  7 +++---
 .../MarkdownEditor/MarkdownEditorImpl.vue     | 24 +++++++++++--------
 .../src/project-view/stores/projectFiles.ts   |  4 ++++
 tsconfig.json                                 |  4 ++--
 6 files changed, 25 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5f158da82720..7bdd3578dbd6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,7 +25,7 @@
 - [New documentation editor provides improved Markdown editing experience, and
   paves the way for new documentation features.][11469]
 - [You can now add images to documentation panel][11547] by pasting them from
-  clipboard or by drag'n'droping image files.
+  clipboard or by drag'n'dropping image files.
 
 [11151]: https://github.com/enso-org/enso/pull/11151
 [11271]: https://github.com/enso-org/enso/pull/11271
diff --git a/app/gui/src/project-view/bindings.ts b/app/gui/src/project-view/bindings.ts
index 63c00ee04498..defe7cb055c6 100644
--- a/app/gui/src/project-view/bindings.ts
+++ b/app/gui/src/project-view/bindings.ts
@@ -12,7 +12,7 @@ export const codeEditorBindings = defineKeybinds('code-editor', {
 export const documentationEditorBindings = defineKeybinds('documentation-editor', {
   toggle: ['Mod+D'],
   openLink: ['Mod+PointerMain'],
-  pasteImage: ['Mod+V'],
+  paste: ['Mod+V'],
 })
 
 export const interactionBindings = defineKeybinds('current-interaction', {
diff --git a/app/gui/src/project-view/components/DocumentationEditor.vue b/app/gui/src/project-view/components/DocumentationEditor.vue
index 0599c1bf9775..e343a07feaf4 100644
--- a/app/gui/src/project-view/components/DocumentationEditor.vue
+++ b/app/gui/src/project-view/components/DocumentationEditor.vue
@@ -163,12 +163,11 @@ const supportedImageTypes: Record<string, { extension: string }> = {
 }
 
 async function handleFileDrop(event: DragEvent) {
-  console.log('HANDLE FILE DROP')
   if (!event.dataTransfer?.items) return
   for (const item of event.dataTransfer.items) {
-    if (item.kind !== 'file' || !(item.type in supportedImageTypes)) return
+    if (item.kind !== 'file' || !Object.hasOwn(supportedImageTypes, item.type)) continue
     const file = item.getAsFile()
-    if (!file) return
+    if (!file) continue
     const clientPos = new Vec2(event.clientX, event.clientY)
     event.stopPropagation()
     event.preventDefault()
@@ -177,7 +176,7 @@ async function handleFileDrop(event: DragEvent) {
 }
 
 const handler = documentationEditorBindings.handler({
-  pasteImage: () => {
+  paste: () => {
     window.navigator.clipboard.read().then(async (items) => {
       if (markdownEditor.value == null) return
       for (const item of items) {
diff --git a/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue b/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
index e31d50fa7d7f..d4eed49e1651 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
+++ b/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
@@ -8,7 +8,7 @@ import {
 import { ensoMarkdown } from '@/components/MarkdownEditor/markdown'
 import VueComponentHost from '@/components/VueComponentHost.vue'
 import { Vec2 } from '@/util/data/vec2'
-import { EditorState } from '@codemirror/state'
+import { EditorState, Text } from '@codemirror/state'
 import { EditorView } from '@codemirror/view'
 import { minimalSetup } from 'codemirror'
 import { type ComponentInstance, onMounted, ref, toRef, useCssModule, watch } from 'vue'
@@ -50,20 +50,24 @@ onMounted(() => {
 
 const editing = ref(false)
 
+/** Replace text in given document range with `text`, putting text cursor after inserted text. */
+function putTextAt(text: string, from: number, to: number) {
+  const insert = Text.of([text])
+  editorView.dispatch({
+    changes: { from, to, insert },
+    selection: { anchor: from + insert.length },
+  })
+}
+
 defineExpose({
   putText: (text: string) => {
-    const range = editorView.state.selection.ranges[0]!
-    editorView.dispatch({
-      changes: { from: range.from, to: range.to, insert: text },
-      selection: { anchor: range.from + text.length },
-    })
+    const range = editorView.state.selection.main
+    putTextAt(text, range.from, range.to)
   },
+  putTextAt,
   putTextAtCoords: (text: string, coords: Vec2) => {
     const pos = editorView.posAtCoords(coords, false)
-    editorView.dispatch({
-      changes: { from: pos, to: pos, insert: text },
-      selection: { anchor: pos + text.length },
-    })
+    putTextAt(text, pos, pos)
   },
 })
 </script>
diff --git a/app/gui/src/project-view/stores/projectFiles.ts b/app/gui/src/project-view/stores/projectFiles.ts
index 0c1e1581e3b1..aee538a2d5b1 100644
--- a/app/gui/src/project-view/stores/projectFiles.ts
+++ b/app/gui/src/project-view/stores/projectFiles.ts
@@ -75,6 +75,10 @@ export function useProjectFiles(projectStore: {
     )
   }
 
+  /**
+   * Check if directory exists. If it does not, or it is a file, `Ok(false)` is returned.
+   * In case of error, the directory existence is not confirmed nor disproved.
+   */
   async function dirExists(path: Path): Promise<Result<boolean>> {
     const info = await lsRpc.fileInfo(path)
     if (info.ok) return Ok(info.value.attributes.kind.type == 'Directory')
diff --git a/tsconfig.json b/tsconfig.json
index 25cb90424954..67c1ca819316 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,6 +1,6 @@
 {
   "compilerOptions": {
-    "lib": ["ES2021", "DOM", "DOM.Iterable"],
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "composite": true,
     "allowSyntheticDefaultImports": true,
     "esModuleInterop": true,
@@ -19,7 +19,7 @@
     "resolveJsonModule": true,
     "sourceMap": true,
     "skipLibCheck": true,
-    "target": "ES2021",
+    "target": "ES2022",
     "jsx": "react-jsx"
   }
 }

From 26dc4f7041dbd1390779128b45c818403d342847 Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Fri, 15 Nov 2024 13:24:21 +0100
Subject: [PATCH 11/15] Apply review - custom link parsing

---
 .../MarkdownEditor/markdown/decoration.ts     |  10 +-
 .../MarkdownEditor/markdown/lezer.d.ts        |  11 +
 .../MarkdownEditor/markdown/parse.ts          | 225 +++++++++++++++++-
 3 files changed, 238 insertions(+), 8 deletions(-)

diff --git a/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts b/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts
index 9c1f5b98fb34..f665b9747fc2 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts
+++ b/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts
@@ -147,16 +147,16 @@ function parseLinkLike(node: SyntaxNode, doc: Text) {
   const urlOpen = textClose.nextSibling // (
   // The parser accepts partial links such as `[Missing url]`.
   if (!urlOpen) return
-  const urlNode = urlOpen.nextSibling
+  const urlNode =
+    urlOpen.nextSibling?.name === 'LinkMark' ?
+      urlOpen.nextSibling?.nextSibling
+    : urlOpen.nextSibling
   // If the URL is empty, this will be the closing 'LinkMark'.
   if (urlNode?.name !== 'URL') return
-  const url = doc.sliceString(urlNode.from, urlNode.to)
-  // See https://spec.commonmark.org/0.31.2/#link-destination
-  const withTriangleBrackets = url.startsWith('<') && url.endsWith('>')
   return {
     textFrom: textOpen.to,
     textTo: textClose.from,
-    url: withTriangleBrackets ? url.slice(1, -1) : url,
+    url: doc.sliceString(urlNode.from, urlNode.to),
   }
 }
 
diff --git a/app/gui/src/project-view/components/MarkdownEditor/markdown/lezer.d.ts b/app/gui/src/project-view/components/MarkdownEditor/markdown/lezer.d.ts
index bf5d1a6726ad..8ed4cfa66cf0 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/markdown/lezer.d.ts
+++ b/app/gui/src/project-view/components/MarkdownEditor/markdown/lezer.d.ts
@@ -32,4 +32,15 @@ declare module '@lezer/markdown' {
     writeElements: (elts: readonly Element[], offset?: number) => Buffer
     finish: (type: number, length: number) => Tree
   }
+
+  export interface InlineDelimiter {
+    readonly type: DelimiterType
+    readonly from: number
+    readonly to: number
+    side: Mark
+  }
+
+  export interface InlineContext {
+    parts: (Element | InlineDelimiter | null)[]
+  }
 }
diff --git a/app/gui/src/project-view/components/MarkdownEditor/markdown/parse.ts b/app/gui/src/project-view/components/MarkdownEditor/markdown/parse.ts
index 5bf27634bbc8..e676b86f2417 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/markdown/parse.ts
+++ b/app/gui/src/project-view/components/MarkdownEditor/markdown/parse.ts
@@ -1,7 +1,17 @@
 import { markdown as baseMarkdown, markdownLanguage } from '@codemirror/lang-markdown'
 import type { Extension } from '@codemirror/state'
 import type { Tree } from '@lezer/common'
-import type { BlockContext, BlockParser, Line, MarkdownParser, NodeSpec } from '@lezer/markdown'
+import type {
+  BlockContext,
+  BlockParser,
+  DelimiterType,
+  InlineContext,
+  InlineDelimiter,
+  InlineParser,
+  Line,
+  MarkdownParser,
+  NodeSpec,
+} from '@lezer/markdown'
 import { Element } from '@lezer/markdown'
 import { assertDefined } from 'ydoc-shared/util/assert'
 
@@ -18,6 +28,7 @@ export function markdown(): Extension {
     extensions: [
       {
         parseBlock: [headerParser, bulletList, orderedList, blockquoteParser, disableSetextHeading],
+        parseInline: [linkParser, imageParser, linkEndParser],
         defineNodes: [blockquoteNode],
       },
     ],
@@ -138,8 +149,8 @@ const blockquoteNode: NodeSpec = {
   },
 }
 
-function elt(type: number, from: number, to: number): Element {
-  return new (Element as any)(type, from, to)
+function elt(type: number, from: number, to: number, children?: readonly Element[]): Element {
+  return new (Element as any)(type, from, to, children)
 }
 
 function isBlockquote(line: Line) {
@@ -196,6 +207,214 @@ function getListIndent(line: Line, pos: number) {
   return indented >= indentAfter + 5 ? indentAfter + 1 : indented
 }
 
+// === Link ===
+
+const enum Mark {
+  None = 0,
+  Open = 1,
+  Close = 2,
+}
+
+const LinkStart: DelimiterType = {}
+const ImageStart: DelimiterType = {}
+
+// function space(ch: number) { return ch == 32 || ch == 9 || ch == 10 || ch == 13 }
+
+const linkParser: InlineParser = {
+  name: 'Link',
+  parse: (cx, next, start) => {
+    return next == 91 /* '[' */ ? cx.addDelimiter(LinkStart, start, start + 1, true, false) : -1
+  },
+}
+
+const imageParser: InlineParser = {
+  name: 'Image',
+  parse: (cx, next, start) => {
+    return next == 33 /* '!' */ && cx.char(start + 1) == 91 /* '[' */ ?
+        cx.addDelimiter(ImageStart, start, start + 2, true, false)
+      : -1
+  },
+}
+
+const linkEndParser: InlineParser = {
+  name: 'LinkEnd',
+  parse: (cx, next, start) => {
+    if (next != 93 /* ']' */) return -1
+    // Scanning back to the next link/image start marker
+    const openDelim = cx.findOpeningDelimiter(LinkStart) ?? cx.findOpeningDelimiter(ImageStart)
+    if (openDelim == null) return -1
+    const part = cx.parts[openDelim] as InlineDelimiter
+    // If this one has been set invalid (because it would produce
+    // a nested link) or there's no valid link here ignore both.
+    if (
+      !part.side ||
+      (cx.skipSpace(part.to) == start && !/[([]/.test(cx.slice(start + 1, start + 2)))
+    ) {
+      cx.parts[openDelim] = null
+      return -1
+    }
+    // Finish the content and replace the entire range in
+    // this.parts with the link/image node.
+    const content = cx.takeContent(openDelim)
+    const link = (cx.parts[openDelim] = finishLink(
+      cx,
+      content,
+      part.type == LinkStart ? getType(cx, 'Link') : getType(cx, 'Image'),
+      part.from,
+      start + 1,
+    ))
+    // Set any open-link markers before this link to invalid.
+    if (part.type == LinkStart)
+      for (let j = 0; j < openDelim; j++) {
+        const p = cx.parts[j]
+        if (p != null && !(p instanceof Element) && p.type == LinkStart) p.side = Mark.None
+      }
+    return link.to
+  },
+}
+
+function finishLink(
+  cx: InlineContext,
+  content: Element[],
+  type: number,
+  start: number,
+  startPos: number,
+) {
+  const { text } = cx,
+    next = cx.char(startPos)
+  let endPos = startPos
+  const LinkMarkType = getType(cx, 'LinkMark')
+  const ImageType = getType(cx, 'Image')
+  content.unshift(elt(LinkMarkType, start, start + (type == ImageType ? 2 : 1)))
+  content.push(elt(LinkMarkType, startPos - 1, startPos))
+  if (next == 40 /* '(' */) {
+    let pos = cx.skipSpace(startPos + 1)
+    const dest = parseURL(text, pos - cx.offset, cx.offset, getType(cx, 'URL'), LinkMarkType)
+    let title
+    if (dest) {
+      const last = dest.at(-1)!
+      pos = cx.skipSpace(last.to)
+      // The destination and title must be separated by whitespace
+      if (pos != last.to) {
+        title = parseLinkTitle(text, pos - cx.offset, cx.offset, getType(cx, 'LinkTitle'))
+        if (title) pos = cx.skipSpace(title.to)
+      }
+    }
+    if (cx.char(pos) == 41 /* ')' */) {
+      content.push(elt(LinkMarkType, startPos, startPos + 1))
+      endPos = pos + 1
+      if (dest) content.push(...dest)
+      if (title) content.push(title)
+      content.push(elt(LinkMarkType, pos, endPos))
+    }
+  } else if (next == 91 /* '[' */) {
+    const label = parseLinkLabel(
+      text,
+      startPos - cx.offset,
+      cx.offset,
+      false,
+      getType(cx, 'LinkLabelType'),
+    )
+    if (label) {
+      content.push(label)
+      endPos = label.to
+    }
+  }
+  return elt(type, start, endPos, content)
+}
+
+// These return `null` when falling off the end of the input, `false`
+// when parsing fails otherwise (for use in the incremental link
+// reference parser).
+function parseURL(
+  text: string,
+  start: number,
+  offset: number,
+  urlType: number,
+  linkMarkType: number,
+): null | false | Element[] {
+  const next = text.charCodeAt(start)
+  if (next == 60 /* '<' */) {
+    for (let pos = start + 1; pos < text.length; pos++) {
+      const ch = text.charCodeAt(pos)
+      if (ch == 62 /* '>' */)
+        return [
+          elt(linkMarkType, start + offset, start + offset + 1),
+          elt(urlType, start + offset + 1, pos + offset),
+          elt(linkMarkType, pos + offset, pos + offset + 1),
+        ]
+      if (ch == 60 || ch == 10 /* '<\n' */) return false
+    }
+    return null
+  } else {
+    let depth = 0,
+      pos = start
+    for (let escaped = false; pos < text.length; pos++) {
+      const ch = text.charCodeAt(pos)
+      if (isSpace(ch)) {
+        break
+      } else if (escaped) {
+        escaped = false
+      } else if (ch == 40 /* '(' */) {
+        depth++
+      } else if (ch == 41 /* ')' */) {
+        if (!depth) break
+        depth--
+      } else if (ch == 92 /* '\\' */) {
+        escaped = true
+      }
+    }
+    return (
+      pos > start ? [elt(urlType, start + offset, pos + offset)]
+      : pos == text.length ? null
+      : false
+    )
+  }
+}
+
+function parseLinkTitle(
+  text: string,
+  start: number,
+  offset: number,
+  linkTitleType: number,
+): null | false | Element {
+  const next = text.charCodeAt(start)
+  if (next != 39 && next != 34 && next != 40 /* '"\'(' */) return false
+  const end = next == 40 ? 41 : next
+  for (let pos = start + 1, escaped = false; pos < text.length; pos++) {
+    const ch = text.charCodeAt(pos)
+    if (escaped) escaped = false
+    else if (ch == end) return elt(linkTitleType, start + offset, pos + 1 + offset)
+    else if (ch == 92 /* '\\' */) escaped = true
+  }
+  return null
+}
+
+function parseLinkLabel(
+  text: string,
+  start: number,
+  offset: number,
+  requireNonWS: boolean,
+  linkLabelType: number,
+): null | false | Element {
+  for (
+    let escaped = false, pos = start + 1, end = Math.min(text.length, pos + 999);
+    pos < end;
+    pos++
+  ) {
+    const ch = text.charCodeAt(pos)
+    if (escaped) escaped = false
+    else if (ch == 93 /* ']' */)
+      return requireNonWS ? false : elt(linkLabelType, start + offset, pos + 1 + offset)
+    else {
+      if (requireNonWS && !isSpace(ch)) requireNonWS = false
+      if (ch == 91 /* '[' */) return false
+      else if (ch == 92 /* '\\' */) escaped = true
+    }
+  }
+  return null
+}
+
 // === Debugging ===
 
 /** Represents the structure of a @{link Tree} in a JSON-compatible format. */

From 65978e5c0e695484765be297d34799b30c5ba413 Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Fri, 15 Nov 2024 13:25:15 +0100
Subject: [PATCH 12/15] Last missing piece of feedback

---
 app/gui/src/project-view/stores/projectFiles.ts | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/app/gui/src/project-view/stores/projectFiles.ts b/app/gui/src/project-view/stores/projectFiles.ts
index aee538a2d5b1..9caf65853c27 100644
--- a/app/gui/src/project-view/stores/projectFiles.ts
+++ b/app/gui/src/project-view/stores/projectFiles.ts
@@ -120,9 +120,7 @@ export function useProjectFiles(projectStore: {
     if (!engineChecksum.ok) return engineChecksum
     const hexChecksum = bytesToHex(checksum.digest())
     if (hexChecksum != engineChecksum.value.checksum) {
-      return Err(
-        `Uploading file failed, checksum does not match. ${hexChecksum} != ${engineChecksum.value.checksum}`,
-      )
+      return Err(`Checksum does not match. ${hexChecksum} != ${engineChecksum.value.checksum}`)
     } else {
       return Ok()
     }

From 0e5f01e06dfc1b9d2d2934bea4765517aa3a9810 Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Mon, 18 Nov 2024 14:09:46 +0100
Subject: [PATCH 13/15] Test for displaying images and one fix in binary
 protocol

---
 app/gui/e2e/project-view/rightPanel.spec.ts     | 11 ++++++++---
 app/gui/src/project-view/mock/engine.ts         | 16 ++++++++++++++++
 app/gui/src/project-view/util/net/dataServer.ts |  7 ++++++-
 3 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/app/gui/e2e/project-view/rightPanel.spec.ts b/app/gui/e2e/project-view/rightPanel.spec.ts
index bc907fbe2d61..3f2eb5ef73b5 100644
--- a/app/gui/e2e/project-view/rightPanel.spec.ts
+++ b/app/gui/e2e/project-view/rightPanel.spec.ts
@@ -7,13 +7,18 @@ import * as locate from './locate'
 test('Main method documentation', async ({ page }) => {
   await actions.goToGraph(page)
 
+  const rightDock = locate.rightDock(page)
   // Documentation panel hotkey opens right-dock.
-  await expect(locate.rightDock(page)).toBeHidden()
+  await expect(rightDock).toBeHidden()
   await page.keyboard.press(`${CONTROL_KEY}+D`)
-  await expect(locate.rightDock(page)).toBeVisible()
+  await expect(rightDock).toBeVisible()
 
   // Right-dock displays main method documentation.
-  await expect(locate.editorRoot(locate.rightDock(page))).toHaveText('The main method')
+  await expect(locate.editorRoot(rightDock)).toContainText('The main method')
+  // All three images are loaded properly
+  await expect(rightDock.getByAltText('Image')).toHaveCount(3)
+  for (const img of await rightDock.getByAltText('Image').all())
+    await expect(img).toHaveJSProperty('naturalWidth', 3)
 
   // Documentation hotkey closes right-dock.p
   await page.keyboard.press(`${CONTROL_KEY}+D`)
diff --git a/app/gui/src/project-view/mock/engine.ts b/app/gui/src/project-view/mock/engine.ts
index 76262c6cf271..2906d68ca75e 100644
--- a/app/gui/src/project-view/mock/engine.ts
+++ b/app/gui/src/project-view/mock/engine.ts
@@ -60,6 +60,12 @@ func2 a =
     r
 
 ## The main method
+
+   Here we test images:
+
+   ![Image](/images/image.png)
+   ![Image](../images/image.png)
+   ![Image](</images/image.png>)
 main =
     five = 5
     ten = 10
@@ -84,6 +90,16 @@ const fileTree = {
       return mainFile
     },
   },
+  images: {
+    get 'image.png'() {
+      return new Uint16Array([
+        20617, 18254, 2573, 2586, 0, 3328, 18505, 21060, 0, 768, 0, 768, 772, 0, 41984, 43014, 140,
+        0, 20501, 21580, 65093, 13106, 11262, 64043, 27756, 24571, 64863, 14906, 12030, 65070,
+        10023, 29424, 11222, 0, 4352, 17481, 21569, 55048, 28771, 24661, 4960, 24672, 52, 768, 161,
+        21933, 29603, 124, 0, 18688, 20037, 44612, 24642, 130,
+      ]).buffer
+    },
+  },
 }
 
 const visualizations = new Map<Uuid, VisualizationConfiguration>()
diff --git a/app/gui/src/project-view/util/net/dataServer.ts b/app/gui/src/project-view/util/net/dataServer.ts
index 87581ebd14bc..a8832f4cc2d7 100644
--- a/app/gui/src/project-view/util/net/dataServer.ts
+++ b/app/gui/src/project-view/util/net/dataServer.ts
@@ -160,10 +160,15 @@ export class DataServer extends ObservableV2<DataServerEvents> {
         return initResult.error.payload
       }
     }
-    this.websocket.send(builder.finish(rootTable).toArrayBuffer())
     const promise = new Promise<T | Error>((resolve) => {
       this.resolveCallbacks.set(messageUuid, resolve)
     })
+    try {
+      this.websocket.send(builder.finish(rootTable).toArrayBuffer())
+    } catch (e: unknown) {
+      this.resolveCallbacks.delete(messageUuid)
+      throw e
+    }
     return promise
   }
 

From bf0c2bd164be0170467442ec7258b8eebe2abaa0 Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Mon, 18 Nov 2024 14:57:34 +0100
Subject: [PATCH 14/15] @Frizi review

---
 .../components/DocumentationEditor.vue        | 35 ++++++++++++-------
 .../MarkdownEditor/__tests__/markdown.test.ts | 15 ++++++++
 .../MarkdownEditor/markdown/decoration.ts     | 19 +++++-----
 .../MarkdownEditor/markdown/parse.ts          |  2 --
 .../src/project-view/stores/projectFiles.ts   |  2 +-
 5 files changed, 48 insertions(+), 25 deletions(-)

diff --git a/app/gui/src/project-view/components/DocumentationEditor.vue b/app/gui/src/project-view/components/DocumentationEditor.vue
index e343a07feaf4..240aae6e4be3 100644
--- a/app/gui/src/project-view/components/DocumentationEditor.vue
+++ b/app/gui/src/project-view/components/DocumentationEditor.vue
@@ -6,12 +6,12 @@ import { fetcherUrlTransformer } from '@/components/MarkdownEditor/imageUrlTrans
 import WithFullscreenMode from '@/components/WithFullscreenMode.vue'
 import { useGraphStore } from '@/stores/graph'
 import { useProjectStore } from '@/stores/project'
-import { ProjectFiles, useProjectFiles } from '@/stores/projectFiles'
+import { useProjectFiles } from '@/stores/projectFiles'
 import { Vec2 } from '@/util/data/vec2'
 import type { ToValue } from '@/util/reactivity'
 import { useToast } from '@/util/toast'
 import { ComponentInstance, computed, reactive, ref, toRef, toValue, watch } from 'vue'
-import type { Path } from 'ydoc-shared/languageServerTypes'
+import type { Path, Uuid } from 'ydoc-shared/languageServerTypes'
 import { Err, Ok, mapOk, withContext, type Result } from 'ydoc-shared/util/data/result'
 import * as Y from 'yjs'
 
@@ -35,12 +35,20 @@ const uploadErrorToast = useToast.error()
 
 type UploadedImagePosition = { type: 'selection' } | { type: 'coords'; coords: Vec2 }
 
+/**
+ * A Project File management API for {@link useDocumentationImages} composable.
+ */
+interface ProjectFilesAPI {
+  projectRootId: Promise<Uuid | undefined>
+  readFileBinary(path: Path): Promise<Result<Blob>>
+  writeFileBinary(path: Path, content: Blob): Promise<Result>
+  pickUniqueName(path: Path, suggestedName: string): Promise<Result<string>>
+  ensureDirExists(path: Path): Promise<Result<void>>
+}
+
 function useDocumentationImages(
   modulePath: ToValue<Path | undefined>,
-  projectFiles: Pick<
-    ProjectFiles,
-    'projectRootId' | 'readFileBinary' | 'writeFileBinary' | 'pickUniqueName' | 'ensureDirExists'
-  >,
+  projectFiles: ProjectFilesAPI,
 ) {
   function urlToPath(url: string): Result<Path> | undefined {
     const modulePathValue = toValue(modulePath)
@@ -66,7 +74,7 @@ function useDocumentationImages(
     return pathUniqueId(path)
   }
 
-  const uploadedImages = reactive(new Map<string, Promise<Blob>>())
+  const currentlyUploading = reactive(new Map<string, Promise<Blob>>())
 
   const transformImageUrl = fetcherUrlTransformer(
     async (url: string) => {
@@ -80,7 +88,7 @@ function useDocumentationImages(
             return {
               location: path,
               uniqueId: id,
-              uploading: computed(() => uploadedImages.has(id)),
+              uploading: computed(() => currentlyUploading.has(id)),
             }
           }),
       )
@@ -88,9 +96,9 @@ function useDocumentationImages(
     async (path) => {
       return withContext(
         () => `Loading documentation image (${pathDebugRepr(path)})`,
-        () => {
-          const uploaded = uploadedImages.get(pathUniqueId(path))
-          return uploaded?.then((blob) => Ok(blob)) ?? projectFiles.readFileBinary(path)
+        async () => {
+          const uploaded = await currentlyUploading.get(pathUniqueId(path))
+          return uploaded ? Ok(uploaded) : projectFiles.readFileBinary(path)
         },
       )
     },
@@ -119,7 +127,7 @@ function useDocumentationImages(
     }
     const path: Path = { rootId, segments: ['images', filename.value] }
     const id = pathUniqueId(path)
-    uploadedImages.set(id, blobPromise)
+    currentlyUploading.set(id, blobPromise)
 
     const insertedLink = `\n![Image](/images/${encodeURI(filename.value)})\n`
     switch (position.type) {
@@ -128,6 +136,7 @@ function useDocumentationImages(
         break
       case 'coords':
         markdownEditor.value.putTextAtCoord(insertedLink, position.coords)
+        break
     }
     try {
       const blob = await blobPromise
@@ -135,7 +144,7 @@ function useDocumentationImages(
       if (!uploadResult.ok)
         uploadErrorToast.reportError(uploadResult.error, 'Failed to upload image')
     } finally {
-      uploadedImages.delete(id)
+      currentlyUploading.delete(id)
     }
   }
 
diff --git a/app/gui/src/project-view/components/MarkdownEditor/__tests__/markdown.test.ts b/app/gui/src/project-view/components/MarkdownEditor/__tests__/markdown.test.ts
index 82625a18dd17..7d06fdcbf010 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/__tests__/markdown.test.ts
+++ b/app/gui/src/project-view/components/MarkdownEditor/__tests__/markdown.test.ts
@@ -104,6 +104,21 @@ test.each([
       alt: '',
     },
   },
+  {
+    markdown: '![](<https://www.example.com/The image.avif>)',
+    image: {
+      src: 'https://www.example.com/The image.avif',
+      alt: '',
+    },
+  },
+  {
+    markdown: '![](<https://www.example.com/The image.avif)',
+    image: null,
+  },
+  {
+    markdown: '![](https://www.example.com/The image.avif)',
+    image: null,
+  },
   {
     markdown: '![Image](https://www.example.com/image.avif',
     image: null,
diff --git a/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts b/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts
index f665b9747fc2..d6457632a160 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts
+++ b/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts
@@ -144,15 +144,8 @@ function parseLinkLike(node: SyntaxNode, doc: Text) {
   if (!textOpen) return
   const textClose = textOpen.nextSibling // ]
   if (!textClose) return
-  const urlOpen = textClose.nextSibling // (
-  // The parser accepts partial links such as `[Missing url]`.
-  if (!urlOpen) return
-  const urlNode =
-    urlOpen.nextSibling?.name === 'LinkMark' ?
-      urlOpen.nextSibling?.nextSibling
-    : urlOpen.nextSibling
-  // If the URL is empty, this will be the closing 'LinkMark'.
-  if (urlNode?.name !== 'URL') return
+  const urlNode = findNextSiblingNamed(textClose, 'URL')
+  if (!urlNode) return
   return {
     textFrom: textOpen.to,
     textTo: textClose.from,
@@ -271,3 +264,11 @@ class ImageWidget extends WidgetType {
     this.container = undefined
   }
 }
+
+function findNextSiblingNamed(node: SyntaxNode, name: string) {
+  for (let sibling = node.nextSibling; sibling != null; sibling = sibling.nextSibling) {
+    if (sibling.name === name) {
+      return node
+    }
+  }
+}
diff --git a/app/gui/src/project-view/components/MarkdownEditor/markdown/parse.ts b/app/gui/src/project-view/components/MarkdownEditor/markdown/parse.ts
index e676b86f2417..589a2a00ca22 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/markdown/parse.ts
+++ b/app/gui/src/project-view/components/MarkdownEditor/markdown/parse.ts
@@ -218,8 +218,6 @@ const enum Mark {
 const LinkStart: DelimiterType = {}
 const ImageStart: DelimiterType = {}
 
-// function space(ch: number) { return ch == 32 || ch == 9 || ch == 10 || ch == 13 }
-
 const linkParser: InlineParser = {
   name: 'Link',
   parse: (cx, next, start) => {
diff --git a/app/gui/src/project-view/stores/projectFiles.ts b/app/gui/src/project-view/stores/projectFiles.ts
index 9caf65853c27..5fe0da0e7466 100644
--- a/app/gui/src/project-view/stores/projectFiles.ts
+++ b/app/gui/src/project-view/stores/projectFiles.ts
@@ -55,7 +55,7 @@ export function useProjectFiles(projectStore: {
   }
 
   /** Check if directory exists and try to create one if missing. */
-  async function ensureDirExists(path: Path) {
+  async function ensureDirExists(path: Path): Promise<Result<void>> {
     const exists = await dirExists(path)
     if (!exists.ok) return exists
     if (exists.value) return Ok()

From a674970aa2c32449892003265626b7312a142c7d Mon Sep 17 00:00:00 2001
From: Adam Obuchowicz <adam.obuchowicz@enso.org>
Date: Tue, 19 Nov 2024 13:44:37 +0100
Subject: [PATCH 15/15] stupid bug

---
 .../components/MarkdownEditor/MarkdownEditorImpl.vue      | 8 ++++++--
 .../components/MarkdownEditor/markdown/decoration.ts      | 4 +++-
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue b/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
index d4eed49e1651..8443e99f26a3 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
+++ b/app/gui/src/project-view/components/MarkdownEditor/MarkdownEditorImpl.vue
@@ -50,9 +50,13 @@ onMounted(() => {
 
 const editing = ref(false)
 
-/** Replace text in given document range with `text`, putting text cursor after inserted text. */
+/**
+ * Replace text in given document range with `text`, putting text cursor after inserted text.
+ *
+ * If text contains multiple lines, it should use '\n', not '\r\n' for line endings.
+ */
 function putTextAt(text: string, from: number, to: number) {
-  const insert = Text.of([text])
+  const insert = Text.of(text.split('\n'))
   editorView.dispatch({
     changes: { from, to, insert },
     selection: { anchor: from + insert.length },
diff --git a/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts b/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts
index d6457632a160..5b87dedac2ce 100644
--- a/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts
+++ b/app/gui/src/project-view/components/MarkdownEditor/markdown/decoration.ts
@@ -146,6 +146,8 @@ function parseLinkLike(node: SyntaxNode, doc: Text) {
   if (!textClose) return
   const urlNode = findNextSiblingNamed(textClose, 'URL')
   if (!urlNode) return
+  console.log('RANGE', urlNode.from, urlNode.to)
+  console.log(doc)
   return {
     textFrom: textOpen.to,
     textTo: textClose.from,
@@ -268,7 +270,7 @@ class ImageWidget extends WidgetType {
 function findNextSiblingNamed(node: SyntaxNode, name: string) {
   for (let sibling = node.nextSibling; sibling != null; sibling = sibling.nextSibling) {
     if (sibling.name === name) {
-      return node
+      return sibling
     }
   }
 }