@ltm-blueverse/alpha-semantic-hub 0.7.0

package/explorer/src/workspaces/GraphWorkspace/graphViewCopy.ts

@@ -0,0 +1,41 @@
+import type { FocusedUnavailableReason, GroupedViewUnavailableReason } from "./types";
+
+const GROUPED_VIEW_COPY = {
+  "communities-undetected": "Grouped view is unavailable until communities can be detected.",
+  "community-nodes-missing": "Grouped view is unavailable because no community nodes could be created.",
+} as const;
+
+const FOCUSED_MODE_COPY = {
+  "no-selection": "Select a node to inspect in Focused mode.",
+  "grouped-unresolvable": "Focused mode is unavailable for this grouped selection.",
+  "not-in-graph": "Selected item is not available in the current graph.",
+} as const;
+
+export function groupedViewReasonText(
+  reason: GroupedViewUnavailableReason | null | undefined,
+): string | null {
+  if (!reason) {
+    return null;
+  }
+
+  switch (reason.code) {
+    case "communities-undetected":
+      return GROUPED_VIEW_COPY["communities-undetected"];
+    case "community-nodes-missing":
+      return GROUPED_VIEW_COPY["community-nodes-missing"];
+    case "invalid-community-layout":
+      return `Grouped node ${reason.nodeId} has invalid coordinates.`;
+    case "missing-grouped-node":
+      return `Grouped edge ${reason.edgeId} references a missing grouped node.`;
+  }
+}
+
+export function focusedUnavailableReasonText(
+  reason: FocusedUnavailableReason | null | undefined,
+): string | null {
+  if (!reason) {
+    return null;
+  }
+
+  return FOCUSED_MODE_COPY[reason.code];
+}

package/explorer/src/workspaces/GraphWorkspace/localGraphTransition.ts

@@ -0,0 +1,9 @@
+import type { GraphViewMode } from "./types";
+
+export function localGraphRequiresDraftConfirm(
+  viewMode: GraphViewMode,
+  selectedNodeId: string,
+  resolvedNodeId: string,
+): boolean {
+  return viewMode !== "focused" || resolvedNodeId !== selectedNodeId;
+}

package/explorer/src/workspaces/GraphWorkspace/markdownEditorState.ts

@@ -0,0 +1,114 @@
+export type MarkdownResourceRef =
+  | { kind: "context-node"; id: string }
+  | { kind: "agent-memory"; id: string };
+
+export type EditorStatus =
+  | "viewing"
+  | "loading-document"
+  | "editing"
+  | "saving"
+  | "validation-error"
+  | "save-error"
+  | "conflict";
+
+export interface MarkdownEditorError {
+  kind: "validation" | "conflict" | "save" | "network";
+  message: string;
+  field?: string;
+  currentRevision?: string;
+}
+
+export interface MarkdownEditSession {
+  resource: MarkdownResourceRef;
+  baseSource: string;
+  baseRevision: string;
+  draft: string;
+  status: EditorStatus;
+  error: MarkdownEditorError | null;
+}
+
+export interface MarkdownSavedDocument {
+  source: string;
+  revision: string;
+}
+
+export function createLoadingSession(resource: MarkdownResourceRef): MarkdownEditSession {
+  return {
+    resource,
+    baseSource: "",
+    baseRevision: "",
+    draft: "",
+    status: "loading-document",
+    error: null,
+  };
+}
+
+export function createEditSession(
+  resource: MarkdownResourceRef,
+  document: MarkdownSavedDocument,
+): MarkdownEditSession {
+  return {
+    resource,
+    baseSource: document.source,
+    baseRevision: document.revision,
+    draft: document.source,
+    status: "editing",
+    error: null,
+  };
+}
+
+export function updateDraft(
+  session: MarkdownEditSession,
+  draft: string,
+): MarkdownEditSession {
+  return {
+    ...session,
+    draft,
+    status: "editing",
+    error: null,
+  };
+}
+
+export function isDirty(session: MarkdownEditSession | null): boolean {
+  return session !== null && session.draft !== session.baseSource;
+}
+
+export function saveStarted(session: MarkdownEditSession): MarkdownEditSession {
+  if (!isDirty(session)) return session;
+  return { ...session, status: "saving", error: null };
+}
+
+export function saveSucceeded(
+  session: MarkdownEditSession,
+  document: MarkdownSavedDocument,
+): MarkdownEditSession {
+  return {
+    ...session,
+    baseSource: document.source,
+    baseRevision: document.revision,
+    draft: document.source,
+    status: "viewing",
+    error: null,
+  };
+}
+
+export function saveFailed(
+  session: MarkdownEditSession,
+  error: MarkdownEditorError,
+): MarkdownEditSession {
+  const status: EditorStatus =
+    error.kind === "validation"
+      ? "validation-error"
+      : error.kind === "conflict"
+        ? "conflict"
+        : "save-error";
+  return { ...session, status, error };
+}
+
+export function cancelEdit(): null {
+  return null;
+}
+
+export function shouldConfirmDiscard(session: MarkdownEditSession | null): boolean {
+  return isDirty(session) && session?.status !== "saving";
+}

package/explorer/src/workspaces/GraphWorkspace/markdownResourceClient.ts

@@ -0,0 +1,103 @@
+import type {
+  MarkdownEditorError,
+  MarkdownResourceRef,
+} from "./markdownEditorState";
+
+export interface MarkdownDocument {
+  resource: MarkdownResourceRef;
+  source: string;
+  body: string;
+  revision: string;
+  editable: boolean;
+}
+
+export interface MarkdownApplyResult extends MarkdownDocument {
+  changed: boolean;
+}
+
+type ErrorDetail = {
+  code?: string;
+  message?: string;
+  field?: string;
+  current_revision?: string;
+};
+
+export class MarkdownClientError extends Error implements MarkdownEditorError {
+  readonly kind: MarkdownEditorError["kind"];
+  readonly field?: string;
+  readonly currentRevision?: string;
+
+  constructor(error: MarkdownEditorError) {
+    super(error.message);
+    this.name = "MarkdownClientError";
+    this.kind = error.kind;
+    this.field = error.field;
+    this.currentRevision = error.currentRevision;
+  }
+}
+
+function resourceUrl(ref: MarkdownResourceRef): string {
+  return `/api/markdown/${ref.kind}/${encodeURIComponent(ref.id)}`;
+}
+
+async function responseError(response: Response): Promise<MarkdownClientError> {
+  let detail: ErrorDetail = {};
+  try {
+    const payload = (await response.json()) as { detail?: ErrorDetail };
+    if (payload.detail && typeof payload.detail === "object") {
+      detail = payload.detail;
+    }
+  } catch {
+    // A non-JSON response is mapped from its status below.
+  }
+
+  const kind: MarkdownEditorError["kind"] =
+    response.status === 422
+      ? "validation"
+      : response.status === 409
+        ? "conflict"
+        : "save";
+  return new MarkdownClientError({
+    kind,
+    message: detail.message || `Markdown request failed (${response.status}).`,
+    field: detail.field,
+    currentRevision: detail.current_revision,
+  });
+}
+
+async function request<T>(input: RequestInfo | URL, init?: RequestInit): Promise<T> {
+  try {
+    const response = await fetch(input, init);
+    if (!response.ok) {
+      throw await responseError(response);
+    }
+    return (await response.json()) as T;
+  } catch (error) {
+    if (error instanceof MarkdownClientError) throw error;
+    throw new MarkdownClientError({
+      kind: "network",
+      message: "The Markdown service could not be reached. Your draft was kept.",
+    });
+  }
+}
+
+export function readMarkdownResource(
+  ref: MarkdownResourceRef,
+): Promise<MarkdownDocument> {
+  return request<MarkdownDocument>(resourceUrl(ref));
+}
+
+export function applyMarkdownResource(
+  ref: MarkdownResourceRef,
+  markdown: string,
+  expectedRevision: string,
+): Promise<MarkdownApplyResult> {
+  return request<MarkdownApplyResult>(resourceUrl(ref), {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      markdown,
+      expected_revision: expectedRevision,
+    }),
+  });
+}

package/explorer/src/workspaces/GraphWorkspace/markdownUrlSafety.ts

@@ -0,0 +1,29 @@
+/**
+ * URL-safety predicate for the Markdown content viewer.
+ *
+ * Extracted into a pure module so the check can be unit-tested without
+ * importing the MarkdownContentViewer React component, and so the component
+ * module exports only components (react-refresh/only-export-components,
+ * issue #1119). The behaviour is unchanged from the original in-component
+ * implementation: only http, https, mailto, in-document fragments, and
+ * root-relative paths are permitted.
+ */
+
+export function isSafeUrl(url?: string): boolean {
+  if (!url) return false;
+  const trimmed = url.trim();
+  // Reject whitespace-only strings — new URL("", base) would resolve to the base
+  // protocol and produce a false positive. This guards direct callers of the exported
+  // function; markdown parsers normalise whitespace-only destinations to "" which
+  // already fails the !url check above.
+  if (!trimmed) return false;
+  if (trimmed.startsWith("//")) return false;
+  if (trimmed.startsWith("#")) return true;
+  if (trimmed.startsWith("/")) return true;
+  try {
+    const parsed = new URL(trimmed, "http://localhost");
+    return ["http:", "https:", "mailto:"].includes(parsed.protocol);
+  } catch {
+    return false;
+  }
+}

package/explorer/src/workspaces/GraphWorkspace/nodeMarkdownSync.ts

@@ -0,0 +1,81 @@
+export interface NodeMarkdownAttributeUpdate {
+  label: string;
+  content: string;
+  properties: Record<string, unknown>;
+}
+
+export interface GraphNodeMarkdownSnapshot {
+  id: string;
+  type: string;
+  content: string;
+  properties: Record<string, unknown>;
+  valid_from: string | null;
+  valid_until: string | null;
+}
+
+export interface SavedNodeMarkdownAttributeUpdate extends NodeMarkdownAttributeUpdate {
+  nodeType: string;
+  valid_from: string | null;
+  valid_until: string | null;
+}
+
+export class NodeMarkdownRefreshGuard {
+  private readonly generations = new Map<string, number>();
+
+  begin(nodeId: string): number {
+    const generation = (this.generations.get(nodeId) ?? 0) + 1;
+    this.generations.set(nodeId, generation);
+    return generation;
+  }
+
+  invalidate(nodeId: string): void {
+    this.begin(nodeId);
+  }
+
+  isCurrent(nodeId: string, generation: number): boolean {
+    return this.generations.get(nodeId) === generation;
+  }
+}
+
+export function buildNodeMarkdownAttributeUpdate(
+  nodeId: string,
+  content: string,
+  properties: Record<string, unknown>,
+): NodeMarkdownAttributeUpdate {
+  return {
+    label: content || nodeId,
+    content,
+    properties: {
+      ...properties,
+      content,
+    },
+  };
+}
+
+export async function readNodeMarkdownAttributeUpdate(
+  nodeId: string,
+  fetcher: typeof fetch = fetch,
+): Promise<SavedNodeMarkdownAttributeUpdate> {
+  const response = await fetcher(
+    `/api/graph/node?node_id=${encodeURIComponent(nodeId)}`,
+  );
+  if (!response.ok) {
+    throw new Error(`Graph node refresh failed (${response.status}).`);
+  }
+
+  const node = await response.json() as GraphNodeMarkdownSnapshot;
+  if (node.id !== nodeId) {
+    throw new Error("Graph node refresh returned a different resource.");
+  }
+
+  return {
+    ...buildNodeMarkdownAttributeUpdate(
+      node.id,
+      node.content,
+      node.properties ?? {},
+    ),
+    nodeType: node.type,
+    valid_from: node.valid_from ?? null,
+    valid_until: node.valid_until ?? null,
+  };
+}

package/explorer/src/workspaces/GraphWorkspace/pluginRegistryPredicates.ts

@@ -0,0 +1,24 @@
+/**
+ * shouldLoad predicates for the GraphWorkspace lazy plugin registry.
+ *
+ * Extracted into a pure module so the predicates can be unit-tested without
+ * importing the full GraphWorkspace React component. Each predicate gates
+ * whether a plugin's module is lazily imported; none reference temporalState
+ * so temporal scrubber updates never retrigger plugin loading (issue #830).
+ */
+
+export type PluginShouldLoadContext = {
+  panelState: Record<string, boolean>;
+};
+
+export function explorationEffectsShouldLoad({ panelState }: PluginShouldLoadContext): boolean {
+  return Boolean(panelState["effects-panel"]);
+}
+
+export function neighborhoodPanelShouldLoad({ panelState }: PluginShouldLoadContext): boolean {
+  return Boolean(panelState["neighborhood-panel"]);
+}
+
+export function temporalOverlayShouldLoad({ panelState }: PluginShouldLoadContext): boolean {
+  return Boolean(panelState["temporal-panel"]);
+}