Word.insertAnnotations not working when invoked from Ribbon command with Task Pane closed (Shared Runtime)

[dmytro-kachurynets]

Environment

• Host: Word (Desktop/Online)

When using the insertAnnotations() API on a Word paragraph, everything works fine as long as the task pane is open. However, when we try to run the exact same code from a ribbon command (with the task pane closed), insertAnnotations() does not actually insert any annotations (no visible highlights or changes appear in the document).

We confirmed that other Word APIs, such as insertText(), work without any issues from the ribbon command, but insertAnnotations() simply does nothing—no error, no exception, just no annotations. We checked the console logs, and we can see that the calls are being made, but the document remains unchanged.

Repro Steps

1. Configure an add-in using a shared runtime.
2. In the task pane, run a function that calls insertAnnotations() on the current paragraph.
   • Observe that it works correctly, and annotations appear.
3. Close the task pane.
4. Use a ribbon button (command UI) to call the same function.
   • insertAnnotations() is called successfully, but no annotations show up in the document.
5. Compare by calling insertText() (or a different API) from the same ribbon button, which does work when the task pane is closed.

Code Snippet (simplified):

await Word.run(async (context) => {
  const paragraphs = context.document.body.paragraphs;
  paragraphs.load("text");
  await context.sync();
  
  // This works when the task pane is open, but does nothing when it's closed:
  const critiquesList = [{ colorScheme: "blue", start: 0, length: 10 }]; 
  const annotationSet: Word.AnnotationSet = { critiques: critiquesList };
  const insertResult = paragraphs.items[0].insertAnnotations(annotationSet);
  
  await context.sync();
  console.log("insertResult:", insertResult);
});

Observations

• No error is thrown (no exception).
• Other APIs, like insertText(), font.highlightColor, or insertComment(), work from the ribbon without issues.
• In the task pane environment (still using shared runtime), insertAnnotations() does produce visible annotations.

Questions

1. Is insertAnnotations() not fully supported when the task pane is closed—even if using a shared runtime?
2. Are there any known limitations or additional requirements for insertAnnotations() to be effective from the ribbon command scenario?
3. Is there a recommended fallback or a specific build/insider channel needed?

Thanks in advance for any guidance or known workarounds!

[RuizhiSunMS]

Hi @dmytro-kachurynets, thx for reaching out here. Put this case as #9649205 into our backlog. I will involve our experts to investigate. Please be patient since it's near Christmas and related with shared runtime. Will reply here if any update.
Btw, would you please confirm this case only happen in calling this api via ribbon button? If we can repro it with simple js code, the cost for investigation would get cut.

[dmytro-kachurynets]

@RuizhiSunMS Thank you for the update and for adding this case to your backlog. To clarify, the only way to interact with the task pane when it is closed is indeed through the ribbon button. Therefore, it could theoretically be related to the ribbon interaction. However, the main issue appears to be that the insertAnnotations() method does not function when the task pane is closed, even though all preceding code executes correctly. Interestingly, this same code works perfectly fine when the task pane is open.

[RuizhiSunMS]

@dmytro-kachurynets, ok. Then may I ask what code you are using? Is the example code like https://learn.microsoft.com/en-us/javascript/api/word/word.paragraph?view=word-js-preview#word-word-paragraph-insertannotations-member(1) able to repro this? If not, would you please share your code?

[dmytro-kachurynets]

@RuizhiSunMS Yes, I can reproduce the issue. I generated a new application and made minimal changes to simplify the code. Additionally, I recorded a video demonstrating the behavior. You can clearly see that, despite the code executing when the task pane is closed, the insertAnnotations() method does not work. However, when performing the same actions with the task pane open, everything functions as expected.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="TaskPaneApp">
  <Id>32a25690-a5e6-45b8-829e-0dfb708a697b</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="poc-word"/>
  <Description DefaultValue="A template to get started."/>
  <IconUrl DefaultValue="https://localhost:3000/assets/icon-32.png"/>
  <HighResolutionIconUrl DefaultValue="https://localhost:3000/assets/icon-64.png"/>
  <SupportUrl DefaultValue="https://www.contoso.com/help"/>
  <AppDomains>
    <AppDomain>https://www.contoso.com</AppDomain>
  </AppDomains>
  <Hosts>
    <Host Name="Document"/>
  </Hosts>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://localhost:3000/taskpane.html"/>
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <Hosts>
      <Host xsi:type="Document">
        <Runtimes>
          <Runtime resid="Taskpane.Url" lifetime="long" />
        </Runtimes>
        <DesktopFormFactor>
          <GetStarted>
            <Title resid="GetStarted.Title"/>
            <Description resid="GetStarted.Description"/>
            <LearnMoreUrl resid="GetStarted.LearnMoreUrl"/>
          </GetStarted>
          <FunctionFile resid="Taskpane.Url"/>
          <ExtensionPoint xsi:type="PrimaryCommandSurface">
            <OfficeTab id="TabHome">
              <Group id="CommandsGroup">
                <Label resid="CommandsGroup.Label"/>
                <Icon>
                  <bt:Image size="16" resid="Icon.16x16"/>
                  <bt:Image size="32" resid="Icon.32x32"/>
                  <bt:Image size="80" resid="Icon.80x80"/>
                </Icon>
                <Control xsi:type="Button" id="TaskpaneButton">
                  <Label resid="TaskpaneButton.Label"/>
                  <Supertip>
                    <Title resid="TaskpaneButton.Label"/>
                    <Description resid="TaskpaneButton.Tooltip"/>
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Icon.16x16"/>
                    <bt:Image size="32" resid="Icon.32x32"/>
                    <bt:Image size="80" resid="Icon.80x80"/>
                  </Icon>
                  <Action xsi:type="ShowTaskpane">
                    <TaskpaneId>ButtonId1</TaskpaneId>
                    <SourceLocation resid="Taskpane.Url"/>
                  </Action>
                </Control>
              </Group>
            </OfficeTab>
            <CustomTab id="Poc.Tab">
              <Group id="Poc.Group.Test">
                <Label resid="Poc.Test.Label"/>
                <Icon>
                  <bt:Image size="16" resid="Icon.16x16"/>
                  <bt:Image size="32" resid="Icon.32x32"/>
                  <bt:Image size="80" resid="Icon.80x80"/>
                </Icon>
                <Control xsi:type="Button" id="Scan">
                  <Label resid="Test.Label"/>
                  <Supertip>
                    <Title resid="Test.Title" />
                    <Description resid="Test.Description" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Icon.16x16"/>
                    <bt:Image size="32" resid="Icon.32x32"/>
                    <bt:Image size="80" resid="Icon.80x80"/>
                  </Icon>
                  <Action xsi:type="ExecuteFunction">
                    <FunctionName>testCommand</FunctionName>
                  </Action>
                </Control>
              </Group>
              <Label resid="Poc.Tab.Label" />
            </CustomTab>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Icon.16x16" DefaultValue="https://localhost:3000/assets/icon-16.png"/>
        <bt:Image id="Icon.32x32" DefaultValue="https://localhost:3000/assets/icon-32.png"/>
        <bt:Image id="Icon.80x80" DefaultValue="https://localhost:3000/assets/icon-80.png"/>
      </bt:Images>
      <bt:Urls>
        <bt:Url id="GetStarted.LearnMoreUrl" DefaultValue="https://go.microsoft.com/fwlink/?LinkId=276812"/>
        <bt:Url id="Taskpane.Url" DefaultValue="https://localhost:3000/taskpane.html"/>
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="GetStarted.Title" DefaultValue="Get started with your sample add-in!"/>
        <bt:String id="CommandsGroup.Label" DefaultValue="Commands Group"/>
        <bt:String id="TaskpaneButton.Label" DefaultValue="Show Task Pane"/>
        <bt:String id="Poc.Tab.Label" DefaultValue="POC" />
        <bt:String id="Poc.Test.Label" DefaultValue="Test" />
        <bt:String id="Test.Label" DefaultValue="Test Document" />
        <bt:String id="Test.Title" DefaultValue="Test Document" />
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="GetStarted.Description" DefaultValue="Your sample add-in loaded successfully. Go to the HOME tab and click the 'Show Task Pane' button to get started."/>
        <bt:String id="TaskpaneButton.Tooltip" DefaultValue="Click to Show a Task Pane"/>
        <bt:String id="Test.Description" DefaultValue="Scan the document for definitions, references and proofreading" />
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</OfficeApp>

import * as React from "react";
import { createRoot } from "react-dom/client";
import App from "./components/App";
import { FluentProvider, webLightTheme } from "@fluentui/react-components";

/* global document, Office, module, require, HTMLElement */

const title = "Contoso Task Pane Add-in";

const rootElement: HTMLElement | null = document.getElementById("container");
const root = rootElement ? createRoot(rootElement) : undefined;

/* Render application after Office initializes */
Office.onReady(() => {
  console.log("onReady");
  Office.actions.associate("testCommand", async (event) => {
    console.log(event, "event");
    await Word.run(async (context) => {
      const paragraph: Word.Paragraph = context.document.getSelection().paragraphs.getFirst();
      const options: Word.CritiquePopupOptions = {
        brandingTextResourceId: "PG.TabLabel",
        subtitleResourceId: "PG.HelpCommand.TipTitle",
        titleResourceId: "PG.HelpCommand.Label",
        suggestions: ["suggestion 1", "suggestion 2", "suggestion 3"],
      };
      const critique1: Word.Critique = {
        colorScheme: Word.CritiqueColorScheme.red,
        start: 1,
        length: 3,
        popupOptions: options,
      };
      const critique2: Word.Critique = {
        colorScheme: Word.CritiqueColorScheme.green,
        start: 6,
        length: 1,
        popupOptions: options,
      };
      const critique3: Word.Critique = {
        colorScheme: Word.CritiqueColorScheme.blue,
        start: 10,
        length: 3,
        popupOptions: options,
      };
      const critique4: Word.Critique = {
        colorScheme: Word.CritiqueColorScheme.lavender,
        start: 14,
        length: 3,
        popupOptions: options,
      };
      const critique5: Word.Critique = {
        colorScheme: Word.CritiqueColorScheme.berry,
        start: 18,
        length: 10,
        popupOptions: options,
      };
      const annotationSet: Word.AnnotationSet = {
        critiques: [critique1, critique2, critique3, critique4, critique5],
      };

      const annotationIds = paragraph.insertAnnotations(annotationSet);

      await context.sync();

      console.log("Annotations inserted:", annotationIds.value);
    });
    event.completed();
  });
  root?.render(
    <FluentProvider theme={webLightTheme}>
      <App title={title} />
    </FluentProvider>
  );
});

if ((module as any).hot) {
  (module as any).hot.accept("./components/App", () => {
    const NextApp = require("./components/App").default;
    root?.render(NextApp);
  });
}

output.compress-video-online.com.mp4