Store application data in DOCX

// A user action, not module scope: the guards below return early, and `return`
// is only legal inside a function.
async function attachFinding() {
  const doc = superdoc.activeEditor?.doc;
  // `capture()` reports readiness; `current()` does not. A worker-backed read is
  // `pending` or `stale` while it settles and still carries the previous range,
  // so writing from it anchors the record to the user's earlier selection.
  //
  // Read `target`, not `selectionTarget`: `target` is always a `TextTarget`
  // (one segment per paragraph the selection touches), which is what lets a
  // selection spanning multiple paragraphs attach as one record.
  // `selectionTarget` collapses a multi-paragraph selection to its first/last
  // endpoints and cannot express that.
  const capture = superdoc.ui.selection.capture();
  const target = capture?.status === 'ready' ? capture.target : null;

  // Anchoring is one or more non-empty text ranges — one segment per
  // paragraph — in the main document **body**. Check every part of that
  // before writing, rather than handling rejections:
  //
  // - Every segment must be non-empty.
  // - `story` is per-target: a non-body target (header, footer, footnote,
  //   endnote, textbox) is rejected outright, since the adapter resolves
  //   paragraphs against the main document part only.
  // - A selection crossing deleted tracked text reports `coordinateSpace:
  //   'tracked'`, and the anchor rewrite searches visible `w:t` runs only, so
  //   the same offsets address different characters.
  //
  // These guards are necessary but not sufficient. A selection crossing a
  // table-cell or section boundary still throws, and nothing in the public
  // selection shape reports that ahead of time, so the catch below is the
  // only place that case can be handled.
  if (!doc || !target) return;
  if (target.coordinateSpace === 'tracked') return;
  if (target.segments.length === 0) return;
  if (target.segments.some((segment) => segment.range.start === segment.range.end)) return;
  if (target.story !== undefined && target.story.storyType !== 'body') return;

  // `attach()` throws for several ordinary cases instead of returning an
  // unsuccessful receipt: when the id already exists (including the second time
  // this action runs), when segments are not contiguous paragraphs (or cross a
  // table-cell/section boundary), when a segment overlaps a content control,
  // a hyperlink, or a simple field (`w:fldSimple`, code and cached result
  // alike — a complex field's cached result text, outside any wrapper, is
  // the one field-adjacent case that IS attachable), and when a paragraph is
  // not in the main document part.
  //
  // Use try/catch rather than `.catch()`. This facade is typed `MaybePromise`, so
  // on a synchronous host `attach()` returns the receipt itself and has no
  // `.catch` method, and a synchronous validation throw happens before any
  // promise exists to reject.
  try {
    const receipt = await doc.metadata.attach({
      id: 'finding-42',
      namespace: 'urn:example:review',
      target,
      payload: { sourceId: 'source-7', justification: 'Verify this statement' },
    });
    if (!receipt.success) reportToUser(receipt.failure.message);
  } catch (error) {
    reportToUser(error instanceof Error ? error.message : String(error));
  }
}

import type { SelectionTarget, TextTarget } from 'superdoc/ui';

// Both endpoints must be `text` to compare positions at all: a `nodeEdge`
// endpoint carries a node reference rather than a block and offset.
//
// Compare the whole story, not just its `storyType`. Two different headers are
// both `headerFooterPart`, and block ids are only unique within a story, so
// comparing the type alone lets an anchor in one header match a control in
// another. The Document API has an internal canonical key for this; until it is
// public, discriminate on the fields that identify each variant.
const storyKey = (story: SelectionTarget['story']) => {
  if (!story) return 'body';
  switch (story.storyType) {
    case 'headerFooterPart':
      return `headerFooterPart:${story.refId}`;
    case 'headerFooterSlot':
      return `headerFooterSlot:${story.section.sectionId}:${story.headerFooterKind}:${story.variant}`;
    case 'footnote':
    case 'endnote':
      return `${story.storyType}:${story.noteId}`;
    case 'textbox':
      return `textbox:${story.textboxId}`;
    default:
      return 'body';
  }
};

// `anchor.target` is a plain `SelectionTarget` for a single-paragraph anchor
// (unchanged since v1), or a `TextTarget` for one spanning multiple
// paragraphs — one control per segment, all sharing the clicked tag. A single
// clicked control is always confined to one paragraph, so match its range
// against ANY ONE of the anchor's segments rather than the whole anchor's
// start-to-end span.
const controlMatchesAnchor = (anchor: SelectionTarget | TextTarget, control: SelectionTarget) => {
  if (control.start.kind !== 'text' || control.end.kind !== 'text') return false;
  if (control.start.blockId !== control.end.blockId) return false;
  if (storyKey(anchor.story) !== storyKey(control.story)) return false;
  const controlBlockId = control.start.blockId;
  const controlStart = control.start.offset;
  const controlEnd = control.end.offset;
  if (anchor.kind === 'text') {
    return anchor.segments.some(
      (segment) =>
        segment.blockId === controlBlockId && segment.range.start === controlStart && segment.range.end === controlEnd,
    );
  }
  if (anchor.start.kind !== 'text' || anchor.end.kind !== 'text') return false;
  return (
    anchor.start.blockId === controlBlockId && anchor.start.offset === controlStart && anchor.end.offset === controlEnd
  );
};

editorShell.addEventListener('pointerdown', async (event) => {
  const doc = superdoc.activeEditor?.doc;
  if (!doc) return;

  const context = superdoc.ui.viewport.contextAt({ x: event.clientX, y: event.clientY });
  // Hits are innermost-first, and a metadata anchor can contain an ordinary
  // nested control. Test every content-control hit rather than the innermost,
  // or a nested control shadows the anchor that encloses it.
  //
  // Metadata anchors live only in the body. Painted content-control hits carry
  // a story locator for non-body controls; reject those before either body-only
  // metadata lookup, even when an id and tag collide with a body anchor.
  for (const hit of context.entities.filter((entity) => entity.type === 'contentControl')) {
    if (!hit.tag) continue;
    const paintedStory = hit.story;
    if (
      paintedStory !== undefined &&
      (paintedStory === null ||
        typeof paintedStory !== 'object' ||
        !('kind' in paintedStory) ||
        paintedStory.kind !== 'story' ||
        !('storyType' in paintedStory) ||
        paintedStory.storyType !== 'body')
    )
      continue;
    const story = paintedStory === undefined ? undefined : ({ kind: 'story', storyType: 'body' } as const);
    // A metadata anchor is a hidden **inline** content control, so `kind` below
    // must say `inline`. Read it from the hit rather than hardcoding it: `scope`
    // is absent when the painted control carries no scope attribute, and a
    // block control cannot be an anchor, so both cases skip.
    if (hit.scope !== 'inline') continue;

    // Read the control through the Document API rather than the UI catalog.
    // `ui.contentControls.list()` schedules its read and returns whatever is
    // cached, so an early click sees an empty or stale array; the awaited
    // Document API call always answers about the current document.
    //
    // Compare the whole range, not just the block: a colliding tag can sit in
    // the same paragraph as the real anchor.
    //
    // `get()` throws rather than returning null for an id it cannot find, and
    // an uncaught throw here would surface as an unhandled rejection from this
    // listener. Treat a failed lookup as "not this hit" and keep scanning.
    let control: Awaited<ReturnType<typeof doc.contentControls.get>> | null = null;
    let anchor: Awaited<ReturnType<typeof doc.metadata.resolve>> | null = null;
    try {
      [control, anchor] = await Promise.all([
        doc.contentControls.get({
          target: { kind: 'inline', nodeType: 'sdt', nodeId: hit.id, ...(story ? { story } : {}) },
        }),
        doc.metadata.resolve({
          id: hit.tag,
          contentControlId: hit.id,
          story: story ?? { kind: 'story', storyType: 'body' },
        }),
      ]);
    } catch {
      continue;
    }
    if (!anchor || !control?.selectionTarget) continue;
    if (!controlMatchesAnchor(anchor.target, control.selectionTarget)) continue;

    const record = await doc.metadata.get({
      id: hit.tag,
      contentControlId: hit.id,
      story: story ?? { kind: 'story', storyType: 'body' },
    });
    if (record) openApplicationRecord(record);
    return;
  }
});