@semiont/core 0.4.20 → 0.4.22

package/dist/index.js

@@ -117,23 +117,211 @@ var PERSISTED_EVENT_TYPES = [
 ];
 
 // src/bus-protocol.ts
-var STREAM_COMMAND_RESULT_TYPES = [
-  // Match flow — search results for binding candidates
-  "match:search-results",
-  "match:search-failed",
-  // Gather flow — assembled context for reference resolution
-  "gather:complete",
-  "gather:failed",
-  "gather:annotation-progress",
-  // Mark flow — AI-assisted annotation progress
-  "mark:progress",
-  "mark:assist-finished",
-  "mark:assist-failed",
-  // Yield flow — resource generation progress
-  "yield:progress",
-  "yield:finished",
-  "yield:failed"
+var RESOURCE_BROADCAST_TYPES = [
+  // Post-unification: job:complete / job:fail carry the "job ended on
+  // this resource" signal that yield:finished / yield:failed used to.
+  // Scope them by resource so every viewer of the affected resource
+  // — not just the initiator — can react (toast, refresh, etc.).
+  "job:complete",
+  "job:fail"
 ];
+var CHANNEL_SCHEMAS = {
+  // ── YIELD FLOW ──────────────────────────────────────────────────
+  "yield:created": null,
+  // StoredEvent
+  "yield:cloned": null,
+  "yield:updated": null,
+  "yield:moved": null,
+  "yield:representation-added": null,
+  "yield:representation-removed": null,
+  "yield:request": "YieldRequestCommand",
+  "yield:create": "YieldCreateCommand",
+  "yield:update": "YieldUpdateCommand",
+  "yield:mv": "YieldMvCommand",
+  "yield:clone": null,
+  // void
+  "yield:clone-token-requested": "YieldCloneTokenRequest",
+  "yield:clone-resource-requested": "YieldCloneResourceRequest",
+  "yield:clone-create": "YieldCloneCreateCommand",
+  "yield:create-ok": "YieldCreateOk",
+  "yield:create-failed": "CommandError",
+  "yield:update-ok": "YieldUpdateOk",
+  "yield:update-failed": null,
+  // YieldUpdateOk & CommandError
+  "yield:move-ok": "YieldMoveOk",
+  "yield:move-failed": null,
+  // { fromUri } & CommandError
+  "yield:clone-token-generated": null,
+  // { correlationId; response: CloneResourceWithTokenResponse }
+  "yield:clone-token-failed": null,
+  // { correlationId } & CommandError
+  "yield:clone-resource-result": null,
+  // { correlationId; response: GetResourceByTokenResponse }
+  "yield:clone-resource-failed": null,
+  // { correlationId } & CommandError
+  "yield:clone-created": "YieldCloneCreated",
+  "yield:clone-create-failed": null,
+  // { correlationId } & CommandError
+  // ── MARK FLOW ───────────────────────────────────────────────────
+  "mark:added": null,
+  // StoredEvent
+  "mark:removed": null,
+  "mark:body-updated": null,
+  "mark:entity-tag-added": null,
+  "mark:entity-tag-removed": null,
+  "mark:entity-type-added": null,
+  "mark:archived": null,
+  "mark:unarchived": null,
+  "mark:create-request": "MarkCreateRequest",
+  "mark:create": "MarkCreateCommand",
+  "mark:delete": "MarkDeleteCommand",
+  "mark:update-body": "MarkUpdateBodyCommand",
+  "mark:archive": "MarkArchiveCommand",
+  "mark:unarchive": "MarkUnarchiveCommand",
+  "mark:update-entity-types": "MarkUpdateEntityTypesCommand",
+  "mark:add-entity-type": "MarkAddEntityTypeCommand",
+  "mark:create-ok": "MarkCreateOk",
+  "mark:create-failed": "CommandError",
+  "mark:delete-ok": "MarkDeleteOk",
+  "mark:delete-failed": "CommandError",
+  "mark:body-update-failed": "CommandError",
+  "mark:entity-type-add-failed": "CommandError",
+  "mark:select-comment": "SelectionData",
+  "mark:select-tag": "SelectionData",
+  "mark:select-assessment": "SelectionData",
+  "mark:select-reference": "SelectionData",
+  "mark:requested": "MarkRequestedEvent",
+  "mark:cancel-pending": null,
+  // void
+  "mark:submit": "MarkSubmitEvent",
+  "mark:assist-request": "MarkAssistRequestEvent",
+  "mark:assist-cancelled": null,
+  // void
+  "mark:progress-dismiss": null,
+  // void
+  "mark:mode-toggled": null,
+  // void
+  "mark:selection-changed": "MarkSelectionChangedEvent",
+  "mark:click-changed": "MarkClickChangedEvent",
+  "mark:shape-changed": "MarkShapeChangedEvent",
+  // ── BIND FLOW ───────────────────────────────────────────────────
+  "bind:initiate": "BindInitiateCommand",
+  "bind:update-body": "BindUpdateBodyCommand",
+  "bind:body-updated": "BindBodyUpdated",
+  "bind:body-update-failed": "CommandError",
+  // ── MATCH FLOW ──────────────────────────────────────────────────
+  "match:search-requested": "MatchSearchRequest",
+  "match:search-results": "MatchSearchResult",
+  "match:search-failed": "MatchSearchFailed",
+  // ── GATHER FLOW ─────────────────────────────────────────────────
+  "gather:requested": "GatherAnnotationRequest",
+  "gather:complete": "GatherAnnotationComplete",
+  "gather:failed": null,
+  // { correlationId; annotationId } & CommandError
+  "gather:resource-requested": "GatherResourceRequest",
+  "gather:resource-complete": "GatherResourceComplete",
+  "gather:resource-failed": null,
+  // { correlationId; resourceId } & CommandError
+  "gather:summary-requested": "GatherSummaryRequest",
+  "gather:summary-result": null,
+  // { correlationId; response: Record<string, unknown> }
+  "gather:summary-failed": null,
+  // { correlationId } & CommandError
+  "gather:annotation-progress": "GatherProgress",
+  "gather:annotation-finished": "GatherAnnotationFinished",
+  "gather:progress": "GatherProgress",
+  "gather:finished": "GatherFinished",
+  // ── BROWSE FLOW ─────────────────────────────────────────────────
+  "browse:resource-requested": "BrowseResourceRequest",
+  "browse:resource-result": "BrowseResourceResult",
+  "browse:resource-failed": null,
+  // { correlationId } & CommandError
+  "browse:resources-requested": "BrowseResourcesRequest",
+  "browse:resources-result": "BrowseResourcesResult",
+  "browse:resources-failed": null,
+  "browse:annotations-requested": "BrowseAnnotationsRequest",
+  "browse:annotations-result": "BrowseAnnotationsResult",
+  "browse:annotations-failed": null,
+  "browse:annotation-requested": "BrowseAnnotationRequest",
+  "browse:annotation-result": "BrowseAnnotationResult",
+  "browse:annotation-failed": null,
+  "browse:events-requested": "BrowseEventsRequest",
+  "browse:events-result": "BrowseEventsResult",
+  "browse:events-failed": null,
+  "browse:annotation-history-requested": "BrowseAnnotationHistoryRequest",
+  "browse:annotation-history-result": "BrowseAnnotationHistoryResult",
+  "browse:annotation-history-failed": null,
+  "browse:annotation-context-requested": "BrowseAnnotationContextRequest",
+  "browse:annotation-context-result": null,
+  // { correlationId; response: Record<string, unknown> }
+  "browse:annotation-context-failed": null,
+  "browse:referenced-by-requested": "BrowseReferencedByRequest",
+  "browse:referenced-by-result": "BrowseReferencedByResult",
+  "browse:referenced-by-failed": null,
+  "browse:entity-types-requested": "BrowseEntityTypesRequest",
+  "browse:entity-types-result": "BrowseEntityTypesResult",
+  "browse:entity-types-failed": null,
+  "browse:directory-requested": "BrowseDirectoryRequest",
+  "browse:directory-result": "BrowseDirectoryResult",
+  "browse:directory-failed": null,
+  // { correlationId; path } & CommandError
+  "browse:click": "BrowseClickEvent",
+  "browse:reference-navigate": "BrowseReferenceNavigateEvent",
+  "browse:entity-type-clicked": "BrowseEntityTypeClickedEvent",
+  // ── SHELL (app-scoped UI events, fire on SemiontBrowser bus) ────
+  "panel:toggle": "BrowsePanelToggleEvent",
+  "panel:open": "BrowsePanelOpenEvent",
+  "panel:close": null,
+  // void
+  "shell:sidebar-toggle": null,
+  // void
+  "tabs:close": "BrowseResourceCloseEvent",
+  "tabs:reorder": "BrowseResourceReorderEvent",
+  "nav:link-clicked": "BrowseLinkClickedEvent",
+  "nav:push": "BrowseRouterPushEvent",
+  "nav:external": null,
+  // includes runtime `cancelFallback: () => void`
+  // ── BECKON FLOW ─────────────────────────────────────────────────
+  "beckon:hover": "BeckonHoverEvent",
+  "beckon:focus": "BeckonFocusEvent",
+  "beckon:sparkle": "BeckonSparkleEvent",
+  // ── JOB FLOW ────────────────────────────────────────────────────
+  "job:started": null,
+  // StoredEvent
+  "job:progress": null,
+  "job:completed": null,
+  "job:failed": null,
+  "job:start": "JobStartCommand",
+  "job:report-progress": "JobReportProgressCommand",
+  "job:complete": "JobCompleteCommand",
+  "job:fail": "JobFailCommand",
+  "job:queued": "JobQueuedEvent",
+  "job:cancel-requested": "JobCancelRequest",
+  "job:status-requested": "JobStatusRequest",
+  "job:create": "JobCreateCommand",
+  "job:claim": "JobClaimCommand",
+  "job:status-result": "JobStatusResult",
+  "job:status-failed": null,
+  // { correlationId } & CommandError
+  "job:created": "JobCreatedResult",
+  "job:create-failed": null,
+  "job:claimed": null,
+  // { correlationId; response: Record<string, unknown> }
+  "job:claim-failed": null,
+  // ── SETTINGS (frontend-only) ────────────────────────────────────
+  "settings:theme-changed": "SettingsThemeChangedEvent",
+  "settings:line-numbers-toggled": null,
+  // void
+  "settings:locale-changed": "SettingsLocaleChangedEvent",
+  "settings:hover-delay-changed": "SettingsHoverDelayChangedEvent",
+  // ── SSE infrastructure ──────────────────────────────────────────
+  "stream-connected": null,
+  // Record<string, never>
+  "replay-window-exceeded": null,
+  // inline payload
+  "bus:resume-gap": null
+  // inline payload
+};
 
 // src/event-utils.ts
 function getAnnotationUriFromEvent(event) {
@@ -404,6 +592,32 @@ function errField(error) {
   return error;
 }
 
+// src/bus-log.ts
+var NODE_BUS_LOG = typeof process !== "undefined" && !!process.env?.SEMIONT_BUS_LOG;
+function busLogEnabled() {
+  const g = globalThis;
+  if (g.__SEMIONT_BUS_LOG__) return true;
+  return NODE_BUS_LOG;
+}
+var traceIdProvider;
+function setBusLogTraceIdProvider(fn) {
+  traceIdProvider = fn;
+}
+function busLog(op, channel, payload, scope) {
+  if (!busLogEnabled()) return;
+  const cidRaw = payload?.correlationId;
+  const cid = typeof cidRaw === "string" ? cidRaw.slice(0, 8) : void 0;
+  let traceId;
+  if (traceIdProvider) {
+    try {
+      traceId = traceIdProvider();
+    } catch {
+    }
+  }
+  const tag = `[bus ${op}] ${channel}` + (scope ? ` scope=${scope}` : "") + (cid ? ` cid=${cid}` : "") + (traceId ? ` trace=${traceId.slice(0, 8)}` : "");
+  console.debug(tag, payload);
+}
+
 // src/annotation-utils.ts
 function findBodyItem(body, identity) {
   if (!Array.isArray(body)) {
@@ -480,7 +694,7 @@ function validateSvgMarkup(svg) {
   return null;
 }
 function assembleAnnotation(request, creator) {
-  const newAnnotationId = generateUuid();
+  const newAnnotationId = annotationId(generateUuid());
   const posSelector = getTextPositionSelector(request.target.selector);
   const svgSelector = getSvgSelector(request.target.selector);
   const fragmentSelector = getFragmentSelector(request.target.selector);
@@ -540,6 +754,734 @@ function applyBodyOperations(body, operations) {
   return bodyArray;
 }
 
+// src/web-annotation-utils.ts
+function getBodySource(body) {
+  if (Array.isArray(body)) {
+    for (const item of body) {
+      if (typeof item === "object" && item !== null && "type" in item && "source" in item) {
+        const itemType = item.type;
+        const itemSource = item.source;
+        if (itemType === "SpecificResource" && typeof itemSource === "string") {
+          return itemSource;
+        }
+      }
+    }
+    return null;
+  }
+  if (typeof body === "object" && body !== null && "type" in body && "source" in body) {
+    const bodyType = body.type;
+    const bodySource = body.source;
+    if (bodyType === "SpecificResource" && typeof bodySource === "string") {
+      return bodySource;
+    }
+  }
+  return null;
+}
+function getBodyType(body) {
+  if (Array.isArray(body)) {
+    if (body.length === 0) {
+      return null;
+    }
+    if (typeof body[0] === "object" && body[0] !== null && "type" in body[0]) {
+      const firstType = body[0].type;
+      if (firstType === "TextualBody" || firstType === "SpecificResource") {
+        return firstType;
+      }
+    }
+    return null;
+  }
+  if (typeof body === "object" && body !== null && "type" in body) {
+    const bodyType = body.type;
+    if (bodyType === "TextualBody" || bodyType === "SpecificResource") {
+      return bodyType;
+    }
+  }
+  return null;
+}
+function isBodyResolved(body) {
+  return getBodySource(body) !== null;
+}
+function getTargetSource(target) {
+  if (typeof target === "string") {
+    return target;
+  }
+  return target.source;
+}
+function getTargetSelector(target) {
+  if (typeof target === "string") {
+    return void 0;
+  }
+  return target.selector;
+}
+function hasTargetSelector(target) {
+  return typeof target !== "string" && target.selector !== void 0;
+}
+function isHighlight(annotation) {
+  return annotation.motivation === "highlighting";
+}
+function isReference(annotation) {
+  return annotation.motivation === "linking";
+}
+function isAssessment(annotation) {
+  return annotation.motivation === "assessing";
+}
+function isComment(annotation) {
+  return annotation.motivation === "commenting";
+}
+function isTag(annotation) {
+  return annotation.motivation === "tagging";
+}
+function getCommentText(annotation) {
+  if (!isComment(annotation)) return void 0;
+  const body = Array.isArray(annotation.body) ? annotation.body[0] : annotation.body;
+  if (body && "value" in body) {
+    return body.value;
+  }
+  return void 0;
+}
+function isStubReference(annotation) {
+  return isReference(annotation) && !isBodyResolved(annotation.body);
+}
+function isResolvedReference(annotation) {
+  return isReference(annotation) && isBodyResolved(annotation.body);
+}
+function getExactText(selector) {
+  if (!selector) {
+    return "";
+  }
+  const selectors = Array.isArray(selector) ? selector : [selector];
+  const quoteSelector = selectors.find((s) => s.type === "TextQuoteSelector");
+  if (quoteSelector) {
+    return quoteSelector.exact;
+  }
+  return "";
+}
+function getAnnotationExactText(annotation) {
+  const selector = getTargetSelector(annotation.target);
+  return getExactText(selector);
+}
+function getPrimarySelector(selector) {
+  if (Array.isArray(selector)) {
+    if (selector.length === 0) {
+      throw new Error("Empty selector array");
+    }
+    const first = selector[0];
+    if (!first) {
+      throw new Error("Invalid selector array");
+    }
+    return first;
+  }
+  return selector;
+}
+function getTextQuoteSelector(selector) {
+  const selectors = Array.isArray(selector) ? selector : [selector];
+  const found = selectors.find((s) => s.type === "TextQuoteSelector");
+  if (!found) return null;
+  return found.type === "TextQuoteSelector" ? found : null;
+}
+function extractBoundingBox(svg) {
+  const viewBoxMatch = svg.match(/<svg[^>]*viewBox="([^"]+)"/);
+  if (viewBoxMatch) {
+    const values = viewBoxMatch[1].split(/\s+/).map(parseFloat);
+    if (values.length === 4 && values.every((v) => !isNaN(v))) {
+      return {
+        x: values[0],
+        y: values[1],
+        width: values[2],
+        height: values[3]
+      };
+    }
+  }
+  const svgTagMatch = svg.match(/<svg[^>]*>/);
+  if (svgTagMatch) {
+    const svgTag = svgTagMatch[0];
+    const widthMatch = svgTag.match(/width="([^"]+)"/);
+    const heightMatch = svgTag.match(/height="([^"]+)"/);
+    if (widthMatch && heightMatch) {
+      const width = parseFloat(widthMatch[1]);
+      const height = parseFloat(heightMatch[1]);
+      if (!isNaN(width) && !isNaN(height)) {
+        return { x: 0, y: 0, width, height };
+      }
+    }
+  }
+  return null;
+}
+
+// src/resource-utils.ts
+function getResourceId(resource) {
+  if (!resource) return void 0;
+  return resource["@id"] || void 0;
+}
+function getPrimaryRepresentation(resource) {
+  if (!resource?.representations) return void 0;
+  const reps = Array.isArray(resource.representations) ? resource.representations : [resource.representations];
+  return reps[0];
+}
+function getPrimaryMediaType(resource) {
+  return getPrimaryRepresentation(resource)?.mediaType;
+}
+function getChecksum(resource) {
+  return getPrimaryRepresentation(resource)?.checksum;
+}
+function getLanguage(resource) {
+  return getPrimaryRepresentation(resource)?.language;
+}
+function getStorageUri(resource) {
+  return getPrimaryRepresentation(resource)?.storageUri;
+}
+function getCreator(resource) {
+  if (!resource?.wasAttributedTo) return void 0;
+  return Array.isArray(resource.wasAttributedTo) ? resource.wasAttributedTo[0] : resource.wasAttributedTo;
+}
+function getDerivedFrom(resource) {
+  if (!resource?.wasDerivedFrom) return void 0;
+  return Array.isArray(resource.wasDerivedFrom) ? resource.wasDerivedFrom[0] : resource.wasDerivedFrom;
+}
+function isArchived(resource) {
+  return resource?.archived === true;
+}
+function getResourceEntityTypes(resource) {
+  return resource?.entityTypes || [];
+}
+function isDraft(resource) {
+  return resource?.isDraft === true;
+}
+function getNodeEncoding(charset) {
+  const normalized = charset.toLowerCase().replace(/[-_]/g, "");
+  const charsetMap = {
+    "utf8": "utf8",
+    "iso88591": "latin1",
+    "latin1": "latin1",
+    "ascii": "ascii",
+    "usascii": "ascii",
+    "utf16le": "utf16le",
+    "ucs2": "ucs2",
+    "binary": "binary",
+    "windows1252": "latin1",
+    // Windows-1252 is a superset of Latin-1
+    "cp1252": "latin1"
+  };
+  return charsetMap[normalized] || "utf8";
+}
+function decodeRepresentation(buffer, mediaType) {
+  const charsetMatch = mediaType.match(/charset=([^\s;]+)/i);
+  const charset = (charsetMatch?.[1] || "utf-8").toLowerCase();
+  const encoding = getNodeEncoding(charset);
+  return buffer.toString(encoding);
+}
+
+// src/bridged-channels.ts
+var BRIDGED_CHANNELS = [
+  "browse:resources-result",
+  "browse:resources-failed",
+  "browse:resource-result",
+  "browse:resource-failed",
+  "browse:annotations-result",
+  "browse:annotations-failed",
+  "browse:annotation-result",
+  "browse:annotation-failed",
+  "browse:annotation-history-result",
+  "browse:annotation-history-failed",
+  "browse:events-result",
+  "browse:events-failed",
+  "browse:referenced-by-result",
+  "browse:referenced-by-failed",
+  "browse:entity-types-result",
+  "browse:entity-types-failed",
+  "browse:directory-result",
+  "browse:directory-failed",
+  "browse:annotation-context-result",
+  "browse:annotation-context-failed",
+  "mark:delete-ok",
+  "mark:delete-failed",
+  "mark:create-ok",
+  "mark:create-failed",
+  "match:search-results",
+  "match:search-failed",
+  "gather:complete",
+  "gather:failed",
+  "gather:annotation-progress",
+  "gather:annotation-finished",
+  "gather:summary-result",
+  "gather:summary-failed",
+  "bind:body-updated",
+  "bind:body-update-failed",
+  "job:report-progress",
+  "job:complete",
+  "job:fail",
+  "job:status-result",
+  "job:status-failed",
+  "job:created",
+  "job:create-failed",
+  "job:claimed",
+  "job:claim-failed",
+  "yield:clone-token-generated",
+  "yield:clone-token-failed",
+  "yield:clone-resource-result",
+  "yield:clone-resource-failed",
+  "yield:clone-created",
+  "yield:clone-create-failed",
+  "mark:entity-type-added",
+  "beckon:focus",
+  "beckon:sparkle",
+  "bus:resume-gap"
+];
+
+// src/fuzzy-anchor.ts
+function normalizeText(text) {
+  return text.replace(/\s+/g, " ").replace(/[\u2018\u2019]/g, "'").replace(/[\u201C\u201D]/g, '"').replace(/\u2014/g, "--").replace(/\u2013/g, "-").trim();
+}
+function levenshteinDistance(str1, str2) {
+  const len1 = str1.length;
+  const len2 = str2.length;
+  const matrix = [];
+  for (let i = 0; i <= len1; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0; j <= len2; j++) {
+    matrix[0][j] = j;
+  }
+  for (let i = 1; i <= len1; i++) {
+    for (let j = 1; j <= len2; j++) {
+      const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
+      const deletion = matrix[i - 1][j] + 1;
+      const insertion = matrix[i][j - 1] + 1;
+      const substitution = matrix[i - 1][j - 1] + cost;
+      matrix[i][j] = Math.min(deletion, insertion, substitution);
+    }
+  }
+  return matrix[len1][len2];
+}
+function buildContentCache(content) {
+  return {
+    normalizedContent: normalizeText(content),
+    lowerContent: content.toLowerCase()
+  };
+}
+function findBestTextMatch(content, searchText, positionHint, cache) {
+  const maxFuzzyDistance = Math.max(5, Math.floor(searchText.length * 0.05));
+  const exactIndex = content.indexOf(searchText);
+  if (exactIndex !== -1) {
+    return {
+      start: exactIndex,
+      end: exactIndex + searchText.length,
+      matchQuality: "exact"
+    };
+  }
+  const normalizedSearch = normalizeText(searchText);
+  const normalizedIndex = cache.normalizedContent.indexOf(normalizedSearch);
+  if (normalizedIndex !== -1) {
+    let actualPos = 0;
+    let normalizedPos = 0;
+    while (normalizedPos < normalizedIndex && actualPos < content.length) {
+      const char = content[actualPos];
+      const normalizedChar = normalizeText(char);
+      if (normalizedChar) {
+        normalizedPos += normalizedChar.length;
+      }
+      actualPos++;
+    }
+    return {
+      start: actualPos,
+      end: actualPos + searchText.length,
+      matchQuality: "normalized"
+    };
+  }
+  const lowerSearch = searchText.toLowerCase();
+  const caseInsensitiveIndex = cache.lowerContent.indexOf(lowerSearch);
+  if (caseInsensitiveIndex !== -1) {
+    return {
+      start: caseInsensitiveIndex,
+      end: caseInsensitiveIndex + searchText.length,
+      matchQuality: "case-insensitive"
+    };
+  }
+  const windowSize = searchText.length;
+  const searchRadius = Math.min(500, content.length);
+  const searchStart = positionHint !== void 0 ? Math.max(0, positionHint - searchRadius) : 0;
+  const searchEnd = positionHint !== void 0 ? Math.min(content.length, positionHint + searchRadius) : content.length;
+  let bestMatch = null;
+  for (let i = searchStart; i <= searchEnd - windowSize; i++) {
+    const candidate = content.substring(i, i + windowSize);
+    const distance = levenshteinDistance(searchText, candidate);
+    if (distance <= maxFuzzyDistance) {
+      if (!bestMatch || distance < bestMatch.distance) {
+        bestMatch = { start: i, distance };
+      }
+    }
+  }
+  if (bestMatch) {
+    return {
+      start: bestMatch.start,
+      end: bestMatch.start + windowSize,
+      matchQuality: "fuzzy"
+    };
+  }
+  return null;
+}
+function findTextWithContext(content, exact, prefix, suffix, positionHint, cache) {
+  if (!exact) return null;
+  if (positionHint !== void 0 && positionHint >= 0 && positionHint + exact.length <= content.length) {
+    if (content.substring(positionHint, positionHint + exact.length) === exact) {
+      return { start: positionHint, end: positionHint + exact.length };
+    }
+  }
+  const occurrences = [];
+  let index = content.indexOf(exact);
+  while (index !== -1) {
+    occurrences.push(index);
+    index = content.indexOf(exact, index + 1);
+  }
+  if (occurrences.length === 0) {
+    const fuzzyMatch = findBestTextMatch(content, exact, positionHint, cache);
+    if (fuzzyMatch) {
+      return { start: fuzzyMatch.start, end: fuzzyMatch.end };
+    }
+    return null;
+  }
+  if (occurrences.length === 1) {
+    const pos2 = occurrences[0];
+    return { start: pos2, end: pos2 + exact.length };
+  }
+  if (prefix || suffix) {
+    for (const pos2 of occurrences) {
+      const actualPrefixStart = Math.max(0, pos2 - (prefix?.length || 0));
+      const actualPrefix = content.substring(actualPrefixStart, pos2);
+      const actualSuffixEnd = Math.min(content.length, pos2 + exact.length + (suffix?.length || 0));
+      const actualSuffix = content.substring(pos2 + exact.length, actualSuffixEnd);
+      const prefixMatch = !prefix || actualPrefix.endsWith(prefix);
+      const suffixMatch = !suffix || actualSuffix.startsWith(suffix);
+      if (prefixMatch && suffixMatch) {
+        return { start: pos2, end: pos2 + exact.length };
+      }
+    }
+    for (const pos2 of occurrences) {
+      const actualPrefix = content.substring(Math.max(0, pos2 - (prefix?.length || 0)), pos2);
+      const actualSuffix = content.substring(pos2 + exact.length, pos2 + exact.length + (suffix?.length || 0));
+      const fuzzyPrefixMatch = !prefix || actualPrefix.includes(prefix.trim());
+      const fuzzySuffixMatch = !suffix || actualSuffix.includes(suffix.trim());
+      if (fuzzyPrefixMatch && fuzzySuffixMatch) {
+        return { start: pos2, end: pos2 + exact.length };
+      }
+    }
+  }
+  const pos = occurrences[0];
+  return { start: pos, end: pos + exact.length };
+}
+function verifyPosition(content, position, expectedExact) {
+  const actualText = content.substring(position.start, position.end);
+  return actualText === expectedExact;
+}
+
+// src/locales.ts
+var LOCALES = [
+  { code: "ar", nativeName: "\u0627\u0644\u0639\u0631\u0628\u064A\u0629", englishName: "Arabic" },
+  { code: "bn", nativeName: "\u09AC\u09BE\u0982\u09B2\u09BE", englishName: "Bengali" },
+  { code: "cs", nativeName: "\u010Ce\u0161tina", englishName: "Czech" },
+  { code: "da", nativeName: "Dansk", englishName: "Danish" },
+  { code: "de", nativeName: "Deutsch", englishName: "German" },
+  { code: "el", nativeName: "\u0395\u03BB\u03BB\u03B7\u03BD\u03B9\u03BA\u03AC", englishName: "Greek" },
+  { code: "en", nativeName: "English", englishName: "English" },
+  { code: "es", nativeName: "Espa\xF1ol", englishName: "Spanish" },
+  { code: "fa", nativeName: "\u0641\u0627\u0631\u0633\u06CC", englishName: "Persian" },
+  { code: "fi", nativeName: "Suomi", englishName: "Finnish" },
+  { code: "fr", nativeName: "Fran\xE7ais", englishName: "French" },
+  { code: "he", nativeName: "\u05E2\u05D1\u05E8\u05D9\u05EA", englishName: "Hebrew" },
+  { code: "hi", nativeName: "\u0939\u093F\u0928\u094D\u0926\u0940", englishName: "Hindi" },
+  { code: "id", nativeName: "Bahasa Indonesia", englishName: "Indonesian" },
+  { code: "it", nativeName: "Italiano", englishName: "Italian" },
+  { code: "ja", nativeName: "\u65E5\u672C\u8A9E", englishName: "Japanese" },
+  { code: "ko", nativeName: "\uD55C\uAD6D\uC5B4", englishName: "Korean" },
+  { code: "ms", nativeName: "Bahasa Melayu", englishName: "Malay" },
+  { code: "nl", nativeName: "Nederlands", englishName: "Dutch" },
+  { code: "no", nativeName: "Norsk", englishName: "Norwegian" },
+  { code: "pl", nativeName: "Polski", englishName: "Polish" },
+  { code: "pt", nativeName: "Portugu\xEAs", englishName: "Portuguese" },
+  { code: "ro", nativeName: "Rom\xE2n\u0103", englishName: "Romanian" },
+  { code: "sv", nativeName: "Svenska", englishName: "Swedish" },
+  { code: "th", nativeName: "\u0E44\u0E17\u0E22", englishName: "Thai" },
+  { code: "tr", nativeName: "T\xFCrk\xE7e", englishName: "Turkish" },
+  { code: "uk", nativeName: "\u0423\u043A\u0440\u0430\u0457\u043D\u0441\u044C\u043A\u0430", englishName: "Ukrainian" },
+  { code: "vi", nativeName: "Ti\u1EBFng Vi\u1EC7t", englishName: "Vietnamese" },
+  { code: "zh", nativeName: "\u4E2D\u6587", englishName: "Chinese" }
+];
+var localeByCode = new Map(
+  LOCALES.map((locale) => [locale.code.toLowerCase(), locale])
+);
+function getLocaleInfo(code) {
+  if (!code) return void 0;
+  return localeByCode.get(code.toLowerCase());
+}
+function getLocaleNativeName(code) {
+  return getLocaleInfo(code)?.nativeName;
+}
+function getLocaleEnglishName(code) {
+  return getLocaleInfo(code)?.englishName;
+}
+function formatLocaleDisplay(code) {
+  if (!code) return void 0;
+  const info = getLocaleInfo(code);
+  if (!info) return code;
+  return `${info.nativeName} (${code.toLowerCase()})`;
+}
+function getAllLocaleCodes() {
+  return LOCALES.map((l) => l.code);
+}
+
+// src/svg-utils.ts
+function createRectangleSvg(start, end) {
+  const x = Math.min(start.x, end.x);
+  const y = Math.min(start.y, end.y);
+  const width = Math.abs(end.x - start.x);
+  const height = Math.abs(end.y - start.y);
+  return `<svg xmlns="http://www.w3.org/2000/svg"><rect x="${x}" y="${y}" width="${width}" height="${height}"/></svg>`;
+}
+function createPolygonSvg(points) {
+  if (points.length < 3) {
+    throw new Error("Polygon requires at least 3 points");
+  }
+  const pointsStr = points.map((p) => `${p.x},${p.y}`).join(" ");
+  return `<svg xmlns="http://www.w3.org/2000/svg"><polygon points="${pointsStr}"/></svg>`;
+}
+function createCircleSvg(center, radius) {
+  if (radius <= 0) {
+    throw new Error("Circle radius must be positive");
+  }
+  return `<svg xmlns="http://www.w3.org/2000/svg"><circle cx="${center.x}" cy="${center.y}" r="${radius}"/></svg>`;
+}
+function parseSvgSelector(svg) {
+  const rectMatch = svg.match(/<rect\s+([^>]+)\/>/);
+  if (rectMatch && rectMatch[1]) {
+    const attrs = rectMatch[1];
+    const x = parseFloat(attrs.match(/x="([^"]+)"/)?.[1] || "0");
+    const y = parseFloat(attrs.match(/y="([^"]+)"/)?.[1] || "0");
+    const width = parseFloat(attrs.match(/width="([^"]+)"/)?.[1] || "0");
+    const height = parseFloat(attrs.match(/height="([^"]+)"/)?.[1] || "0");
+    return {
+      type: "rect",
+      data: { x, y, width, height }
+    };
+  }
+  const polygonMatch = svg.match(/<polygon\s+points="([^"]+)"/);
+  if (polygonMatch && polygonMatch[1]) {
+    const pointsStr = polygonMatch[1];
+    const points = pointsStr.split(/\s+/).map((pair) => {
+      const [x, y] = pair.split(",").map(parseFloat);
+      return { x, y };
+    });
+    return {
+      type: "polygon",
+      data: { points }
+    };
+  }
+  const circleMatch = svg.match(/<circle\s+([^>]+)\/>/);
+  if (circleMatch && circleMatch[1]) {
+    const attrs = circleMatch[1];
+    const cx = parseFloat(attrs.match(/cx="([^"]+)"/)?.[1] || "0");
+    const cy = parseFloat(attrs.match(/cy="([^"]+)"/)?.[1] || "0");
+    const r = parseFloat(attrs.match(/r="([^"]+)"/)?.[1] || "0");
+    return {
+      type: "circle",
+      data: { cx, cy, r }
+    };
+  }
+  return null;
+}
+function normalizeCoordinates(point, displayWidth, displayHeight, imageWidth, imageHeight) {
+  return {
+    x: point.x / displayWidth * imageWidth,
+    y: point.y / displayHeight * imageHeight
+  };
+}
+function scaleSvgToNative(svg, displayWidth, displayHeight, imageWidth, imageHeight) {
+  const parsed = parseSvgSelector(svg);
+  if (!parsed) return svg;
+  const scaleX = imageWidth / displayWidth;
+  const scaleY = imageHeight / displayHeight;
+  switch (parsed.type) {
+    case "rect": {
+      const { x, y, width, height } = parsed.data;
+      return createRectangleSvg(
+        { x: x * scaleX, y: y * scaleY },
+        { x: (x + width) * scaleX, y: (y + height) * scaleY }
+      );
+    }
+    case "circle": {
+      const { cx, cy, r } = parsed.data;
+      return createCircleSvg(
+        { x: cx * scaleX, y: cy * scaleY },
+        r * Math.min(scaleX, scaleY)
+      );
+    }
+    case "polygon": {
+      const points = parsed.data.points.map((p) => ({
+        x: p.x * scaleX,
+        y: p.y * scaleY
+      }));
+      return createPolygonSvg(points);
+    }
+  }
+  return svg;
+}
+
+// src/text-context.ts
+function extractContext(content, start, end) {
+  const CONTEXT_LENGTH = 64;
+  const MAX_EXTENSION = 32;
+  let prefix;
+  if (start > 0) {
+    let prefixStart = Math.max(0, start - CONTEXT_LENGTH);
+    let extensionCount = 0;
+    while (prefixStart > 0 && extensionCount < MAX_EXTENSION) {
+      const char = content[prefixStart - 1];
+      if (!char || /[\s.,;:!?'"()\[\]{}<>\/\\]/.test(char)) {
+        break;
+      }
+      prefixStart--;
+      extensionCount++;
+    }
+    prefix = content.substring(prefixStart, start);
+  }
+  let suffix;
+  if (end < content.length) {
+    let suffixEnd = Math.min(content.length, end + CONTEXT_LENGTH);
+    let extensionCount = 0;
+    while (suffixEnd < content.length && extensionCount < MAX_EXTENSION) {
+      const char = content[suffixEnd];
+      if (!char || /[\s.,;:!?'"()\[\]{}<>\/\\]/.test(char)) {
+        break;
+      }
+      suffixEnd++;
+      extensionCount++;
+    }
+    suffix = content.substring(end, suffixEnd);
+  }
+  return { prefix, suffix };
+}
+function validateAndCorrectOffsets(content, aiStart, aiEnd, exact) {
+  const textAtOffset = content.substring(aiStart, aiEnd);
+  if (textAtOffset === exact) {
+    const context2 = extractContext(content, aiStart, aiEnd);
+    return {
+      start: aiStart,
+      end: aiEnd,
+      exact,
+      prefix: context2.prefix,
+      suffix: context2.suffix,
+      corrected: false,
+      matchQuality: "exact"
+    };
+  }
+  const cache = buildContentCache(content);
+  const match = findBestTextMatch(content, exact, aiStart, cache);
+  if (!match) {
+    throw new Error(
+      "Cannot find acceptable match for text in content. All search strategies failed. Text may be hallucinated."
+    );
+  }
+  const actualText = content.substring(match.start, match.end);
+  const context = extractContext(content, match.start, match.end);
+  return {
+    start: match.start,
+    end: match.end,
+    exact: actualText,
+    // Use actual text from document, not AI's version
+    prefix: context.prefix,
+    suffix: context.suffix,
+    corrected: true,
+    fuzzyMatched: match.matchQuality !== "exact",
+    matchQuality: match.matchQuality
+  };
+}
+
+// src/text-encoding.ts
+function extractCharset(mediaType) {
+  const charsetMatch = mediaType.match(/charset=([^\s;]+)/i);
+  return (charsetMatch?.[1] || "utf-8").toLowerCase();
+}
+function decodeWithCharset(buffer, mediaType) {
+  const charset = extractCharset(mediaType);
+  const decoder = new TextDecoder(charset);
+  return decoder.decode(buffer);
+}
+
+// src/validation.ts
+var JWTTokenSchema = {
+  parse(token) {
+    if (typeof token !== "string") {
+      throw new Error("Token must be a string");
+    }
+    if (!token || token.length === 0) {
+      throw new Error("Token is required");
+    }
+    const jwtRegex = /^[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]*$/;
+    if (!jwtRegex.test(token)) {
+      throw new Error("Invalid JWT token format");
+    }
+    return token;
+  },
+  safeParse(token) {
+    try {
+      const validated = this.parse(token);
+      return { success: true, data: validated };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : "Invalid JWT token"
+      };
+    }
+  }
+};
+function validateData(schema, data) {
+  try {
+    const validated = schema.parse(data);
+    return { success: true, data: validated };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Validation failed"
+    };
+  }
+}
+function isValidEmail(email2) {
+  if (email2.length < 1 || email2.length > 255) {
+    return false;
+  }
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailRegex.test(email2);
+}
+
+// src/mime-utils.ts
+function getExtensionForMimeType(mimeType) {
+  const map = {
+    "text/plain": "txt",
+    "text/markdown": "md",
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "application/pdf": "pdf"
+  };
+  return map[mimeType] || "dat";
+}
+function isImageMimeType(mimeType) {
+  return mimeType === "image/png" || mimeType === "image/jpeg";
+}
+function isTextMimeType(mimeType) {
+  return mimeType === "text/plain" || mimeType === "text/markdown";
+}
+function isPdfMimeType(mimeType) {
+  return mimeType === "application/pdf";
+}
+function getMimeCategory(mimeType) {
+  if (isTextMimeType(mimeType)) {
+    return "text";
+  }
+  if (isImageMimeType(mimeType) || isPdfMimeType(mimeType)) {
+    return "image";
+  }
+  return "unsupported";
+}
+
 // src/type-guards.ts
 function isString(value) {
   return typeof value === "string";
@@ -635,6 +1577,9 @@ function userToAgent(user) {
   };
 }
 function didToAgent(did) {
+  if (!did) {
+    return { type: "Person", id: "unknown", name: "unknown" };
+  }
   const parts = did.split(":");
   const encoded = parts[parts.length - 1] || "unknown";
   const name = decodeURIComponent(encoded);
@@ -659,11 +1604,14 @@ function deepMerge(base, override) {
 }
 function resolveEnvVars(obj, env) {
   if (typeof obj === "string") {
-    return obj.replace(/\$\{([^}]+)\}/g, (match, varName) => {
-      if (env[varName] === void 0) {
-        throw new Error(`Environment variable ${varName} is not set (referenced in config as ${match})`);
-      }
-      return env[varName];
+    return obj.replace(/\$\{([^}]+)\}/g, (match, expr) => {
+      const sepIdx = expr.indexOf(":-");
+      const varName = sepIdx >= 0 ? expr.slice(0, sepIdx) : expr;
+      const defaultValue = sepIdx >= 0 ? expr.slice(sepIdx + 2) : void 0;
+      const value = env[varName];
+      if (value !== void 0) return value;
+      if (defaultValue !== void 0) return defaultValue;
+      throw new Error(`Environment variable ${varName} is not set (referenced in config as ${match})`);
     });
   }
   if (Array.isArray(obj)) {
@@ -981,6 +1929,6 @@ function getAllPlatformTypes() {
 var CORE_TYPES_VERSION = "0.1.0";
 var SDK_VERSION = "0.1.0";
 
-export { APIError, CORE_TYPES_VERSION, CREATION_METHODS, ConfigurationError, ConflictError, EventBus, NotFoundError, PERSISTED_EVENT_TYPES, SDK_VERSION, STREAM_COMMAND_RESULT_TYPES, ScopedEventBus, ScriptError, SemiontError, UnauthorizedError, ValidationError, accessToken, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseUrl, burstBuffer, cloneToken, createTomlConfigLoader, didToAgent, email, entityType, errField, findBodyItem, generateUuid, getAllPlatformTypes, getAnnotationUriFromEvent, getFragmentSelector, getSvgSelector, getTextPositionSelector, googleCredential, isAnnotationId, isArray, isBoolean, isDefined, isEventRelatedToAnnotation, isFunction, isNull, isNullish, isNumber, isObject, isResourceId, isStoredEvent, isString, isUndefined, isValidPlatformType, jobId, loadTomlConfig, mcpToken, parseEnvironment, refreshToken, resourceAnnotationUri, resourceId, resourceUri, searchQuery, serializePerKey, userDID, userId, userToAgent, userToDid, validateEnvironment, validateSvgMarkup };
+export { APIError, BRIDGED_CHANNELS, CHANNEL_SCHEMAS, CORE_TYPES_VERSION, CREATION_METHODS, ConfigurationError, ConflictError, EventBus, JWTTokenSchema, LOCALES, NotFoundError, PERSISTED_EVENT_TYPES, RESOURCE_BROADCAST_TYPES, SDK_VERSION, ScopedEventBus, ScriptError, SemiontError, UnauthorizedError, ValidationError, accessToken, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseUrl, buildContentCache, burstBuffer, busLog, busLogEnabled, cloneToken, createCircleSvg, createPolygonSvg, createRectangleSvg, createTomlConfigLoader, decodeRepresentation, decodeWithCharset, didToAgent, email, entityType, errField, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, findTextWithContext, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getExtensionForMimeType, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getMimeCategory, getNodeEncoding, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getStorageUri, getSvgSelector, getTargetSelector, getTargetSource, getTextPositionSelector, getTextQuoteSelector, googleCredential, hasTargetSelector, isAnnotationId, isArchived, isArray, isAssessment, isBodyResolved, isBoolean, isComment, isDefined, isDraft, isEventRelatedToAnnotation, isFunction, isHighlight, isImageMimeType, isNull, isNullish, isNumber, isObject, isPdfMimeType, isReference, isResolvedReference, isResourceId, isStoredEvent, isString, isStubReference, isTag, isTextMimeType, isUndefined, isValidEmail, isValidPlatformType, jobId, loadTomlConfig, mcpToken, normalizeCoordinates, normalizeText, parseEnvironment, parseSvgSelector, refreshToken, resourceAnnotationUri, resourceId, resourceUri, scaleSvgToNative, searchQuery, serializePerKey, setBusLogTraceIdProvider, userDID, userId, userToAgent, userToDid, validateAndCorrectOffsets, validateData, validateEnvironment, validateSvgMarkup, verifyPosition };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map