@agimon-ai/doompi-author 0.0.1-alpha.2

package/src/web/components/OpenAuthoringFileToolCard.tsx

@@ -0,0 +1,66 @@
+import {
+  Button,
+  MessageItem,
+  MessageItemBody,
+  MessageItemHeader,
+  MessageItemStatus,
+  toolTone,
+} from '@agimon-ai/doompi-web-components';
+import type { ToolMessageRenderProps } from '@agimon-ai/doompi-web-contracts';
+import { authorFileTab } from './AuthorDocumentPanel.tsx';
+
+export function openAuthoringFileTab(
+  path: string,
+  openTransientTab: ToolMessageRenderProps['openTransientTab'],
+  openTab: ToolMessageRenderProps['openTab'],
+): void {
+  const tab = authorFileTab(path);
+  openTransientTab(tab);
+  openTab(tab.id);
+}
+
+function resultPath(result: ToolMessageRenderProps['result']): string | undefined {
+  if (typeof result?.details !== 'object' || result.details === null || !('path' in result.details)) return undefined;
+  return typeof result.details.path === 'string' ? result.details.path : undefined;
+}
+
+export function OpenAuthoringFileToolCard({
+  args,
+  result,
+  running,
+  isError,
+  openTransientTab,
+  openTab,
+}: ToolMessageRenderProps) {
+  const path = resultPath(result);
+
+  const requestedPath = typeof args.path === 'string' ? args.path : 'document';
+  return (
+    <MessageItem tone={toolTone({ running, isError })}>
+      {() => (
+        <>
+          <MessageItemHeader title="open_authoring_file">
+            <span data-testid="tool-call-open_authoring_file" className="min-w-0 flex-1 truncate text-doom-text">
+              {requestedPath}
+            </span>
+          </MessageItemHeader>
+          <MessageItemBody data-testid="tool-result-open_authoring_file">
+            <MessageItemStatus tone={isError ? 'error' : running ? 'running' : undefined}>
+              {isError ? 'failed' : running ? 'validating' : path === undefined ? 'waiting' : 'ready'}
+            </MessageItemStatus>
+            {!running && !isError && path !== undefined ? (
+              <Button
+                size="xs"
+                variant="outline"
+                data-testid="author-open-file"
+                onClick={() => openAuthoringFileTab(path, openTransientTab, openTab)}
+              >
+                open in Author
+              </Button>
+            ) : null}
+          </MessageItemBody>
+        </>
+      )}
+    </MessageItem>
+  );
+}

package/src/web/components/UseAuthorToolsToolCard.tsx

@@ -0,0 +1,50 @@
+import {
+  collapseLines,
+  MessageItem,
+  MessageItemBody,
+  MessageItemHeader,
+  MessageItemStatus,
+  MessageLines,
+  toolTone,
+} from '@agimon-ai/doompi-web-components';
+import type { ToolMessageRenderProps } from '@agimon-ai/doompi-web-contracts';
+import {
+  useAuthorToolsCallSummary,
+  useAuthorToolsCollapsedLines,
+  useAuthorToolsResultLines,
+} from '../lib/useAuthorToolsToolRender.ts';
+
+/**
+ * The use_author_tools tool's timeline item: Use one capability of the current Author viewport. The shell owns
+ * the frame, the outcome tone, the status badge, and the expand toggle; this
+ * card supplies the header summary and the body lines, and says whether it
+ * hides any so the toggle appears only when it reveals something.
+ */
+export function UseAuthorToolsToolCard({ toolName, args, result, running, isError }: ToolMessageRenderProps) {
+  const lines = useAuthorToolsResultLines(result);
+  const collapsed = collapseLines(lines, useAuthorToolsCollapsedLines, false);
+  return (
+    <MessageItem tone={toolTone({ running, isError })} expandable={collapsed.hidden > 0}>
+      {({ expanded }) => {
+        const view = expanded ? collapseLines(lines, useAuthorToolsCollapsedLines, true) : collapsed;
+        return (
+          <>
+            <MessageItemHeader title={toolName}>
+              <span data-testid={`tool-call-${toolName}`} className="min-w-0 flex-1 truncate text-doom-text">
+                {useAuthorToolsCallSummary(args)}
+              </span>
+            </MessageItemHeader>
+            {view.shown.length > 0 || running || isError ? (
+              <MessageItemBody data-testid={`tool-result-${toolName}`} className="flex flex-col gap-1">
+                {view.shown.length > 0 ? <MessageLines lines={view.shown} /> : null}
+                {view.hidden > 0 ? <MessageItemStatus expands>{view.hidden} more line(s)</MessageItemStatus> : null}
+                {running ? <MessageItemStatus tone="running">running</MessageItemStatus> : null}
+                {isError ? <MessageItemStatus tone="error">failed</MessageItemStatus> : null}
+              </MessageItemBody>
+            ) : null}
+          </>
+        );
+      }}
+    </MessageItem>
+  );
+}

package/src/web/index.ts

@@ -0,0 +1,68 @@
+import { defineWebPlugin, type WebPluginRuntime } from '@agimon-ai/doompi-web-contracts';
+import { authorFileLinks } from './components/AuthorDocumentPanel.tsx';
+import { AuthorPanel } from './components/AuthorPanel.tsx';
+import { startAuthorBrowserBridge } from './api/authorBrowserBridge.ts';
+import { authorChannel } from './stores/authorStore.ts';
+import { DescribeAuthorToolsToolCard } from './components/DescribeAuthorToolsToolCard.tsx';
+import { OpenAuthoringFileToolCard } from './components/OpenAuthoringFileToolCard.tsx';
+import { UseAuthorToolsToolCard } from './components/UseAuthorToolsToolCard.tsx';
+import { recordAuthorCaptureStatus, recordAuthorComposerSubmission } from './stores/authorRequestLifecycle.ts';
+import { authorWorkspace } from './stores/authorWorkspaceStore.ts';
+
+/**
+ * This package's cockpit presence: the named export the generated plugin
+ * registry imports. Plugins are independent, so nothing here depends on
+ * install order; every relation to another plugin resolves by name.
+ */
+function startAuthor(runtime: WebPluginRuntime): () => void {
+  const stopBridge = startAuthorBrowserBridge(runtime);
+  const stopSubmissions = runtime.onComposerSubmitted?.(recordAuthorComposerSubmission) ?? (() => undefined);
+  const stopCaptureStatus = runtime.onCaptureStatus?.(recordAuthorCaptureStatus) ?? (() => undefined);
+  return () => {
+    stopSubmissions();
+    stopCaptureStatus();
+    stopBridge();
+  };
+}
+
+export const webPlugin = defineWebPlugin({
+  id: 'author',
+  dockFaces: [
+    {
+      id: 'authoring',
+      label: 'authoring',
+      order: 30,
+      autoSelect: true,
+      panel: AuthorPanel,
+      requiredMinorMode: 'author',
+      visibility: {
+        subscribe(listener) {
+          const subscription = authorWorkspace.store.subscribe(listener);
+          return () => subscription.unsubscribe();
+        },
+        isVisible(sessionId) {
+          return sessionId !== null && authorWorkspace.store.state.sessions[sessionId]?.focusedDocument !== undefined;
+        },
+      },
+    },
+  ],
+  minorModes: [{ name: 'author', keys: 'o a', order: 45 }],
+  leaderBindings: [
+    {
+      id: 'author.toggle',
+      path: [
+        { key: 'o', label: 'other', detail: 'optional modes and tools' },
+        { key: 'a', label: 'author', detail: 'enable or disable focused document authoring' },
+      ],
+      command: 'minor author',
+    },
+  ],
+  channels: [authorChannel],
+  fileLinks: authorFileLinks,
+  toolRenderers: [
+    { tools: ['open_authoring_file'], message: OpenAuthoringFileToolCard },
+    { tools: ['describe_author_tools'], message: DescribeAuthorToolsToolCard },
+    { tools: ['use_author_tools'], message: UseAuthorToolsToolCard },
+  ],
+  start: startAuthor,
+});

package/src/web/lib/authorGrid.ts

@@ -0,0 +1,124 @@
+import { defineGlobalStore } from '@agimon-ai/doompi-web-contracts';
+import type { AuthorNativeAnchor, AuthorVoiceGridEvidence, AuthorViewportSnapshot } from './authorViewportTypes.ts';
+
+export const AUTHOR_GRID_COLUMNS = 'ABCDEFGH' as const;
+export const AUTHOR_GRID_SIZE = 8;
+
+export interface AuthorGridGeometry {
+  documentPath: string;
+  revision: number;
+  sourceSha256?: string;
+  geometryToken: string;
+  snapshotId: string;
+  viewport: AuthorViewportSnapshot;
+  updatedAt: number;
+}
+
+interface AuthorGridState {
+  sessions: Readonly<Record<string, AuthorGridGeometry>>;
+}
+
+export interface AuthorGridCellResolution {
+  cell: string;
+  column: number;
+  row: number;
+  rect: { x: number; y: number; width: number; height: number };
+  center: { x: number; y: number };
+  evidence: AuthorVoiceGridEvidence;
+}
+
+export interface AuthorGridNativeResolution {
+  anchor: AuthorNativeAnchor;
+  quote?: string;
+}
+
+type AuthorGridNativeResolver = (
+  cell: AuthorGridCellResolution,
+  geometry: AuthorGridGeometry,
+) => AuthorGridNativeResolution | undefined;
+
+const nativeResolvers = new Map<string, AuthorGridNativeResolver>();
+
+export const authorGrid = defineGlobalStore<AuthorGridState>({ sessions: {} });
+
+export function parseAuthorGridCell(cell: string): { cell: string; column: number; row: number } {
+  const normalized = cell.trim().toUpperCase();
+  if (!/^[A-H][1-8]$/u.test(normalized)) throw new Error(`Invalid Author grid cell '${cell}'. Expected A1 through H8.`);
+  return {
+    cell: normalized,
+    column: AUTHOR_GRID_COLUMNS.indexOf(normalized[0] as (typeof AUTHOR_GRID_COLUMNS)[number]),
+    row: Number(normalized[1]) - 1,
+  };
+}
+
+export function updateAuthorGridGeometry(
+  sessionId: string,
+  input: Omit<AuthorGridGeometry, 'geometryToken' | 'snapshotId' | 'updatedAt'>,
+): AuthorGridGeometry {
+  const previous = authorGrid.store.state.sessions[sessionId];
+  const geometry: AuthorGridGeometry = {
+    ...input,
+    geometryToken: crypto.randomUUID(),
+    snapshotId:
+      previous?.documentPath === input.documentPath &&
+      previous.revision === input.revision &&
+      previous.sourceSha256 === input.sourceSha256
+        ? previous.snapshotId
+        : crypto.randomUUID(),
+    updatedAt: Date.now(),
+  };
+  authorGrid.update((state) => ({ ...state, sessions: { ...state.sessions, [sessionId]: geometry } }));
+  return geometry;
+}
+
+export function authorGridGeometry(sessionId: string): AuthorGridGeometry | undefined {
+  return authorGrid.store.state.sessions[sessionId];
+}
+
+export function clearAuthorGridGeometry(sessionId: string): void {
+  authorGrid.update((state) => {
+    if (state.sessions[sessionId] === undefined) return state;
+    const sessions = { ...state.sessions };
+    delete sessions[sessionId];
+    return { ...state, sessions };
+  });
+}
+
+export function registerAuthorGridResolver(sessionId: string, resolver: AuthorGridNativeResolver): () => void {
+  nativeResolvers.set(sessionId, resolver);
+  return () => {
+    if (nativeResolvers.get(sessionId) === resolver) nativeResolvers.delete(sessionId);
+  };
+}
+
+export function resolveAuthorGridNativeAnchor(
+  sessionId: string,
+  cell: AuthorGridCellResolution,
+): AuthorGridNativeResolution {
+  const geometry = authorGridGeometry(sessionId);
+  const resolved = geometry === undefined ? undefined : nativeResolvers.get(sessionId)?.(cell, geometry);
+  if (resolved === undefined)
+    throw new Error('AMBIGUOUS_GRID: The grid cell does not resolve to one visible native document target.');
+  return resolved;
+}
+
+export function resolveAuthorGridCell(
+  sessionId: string,
+  cell: string,
+  expectedGeometryToken: string,
+): AuthorGridCellResolution {
+  const geometry = authorGridGeometry(sessionId);
+  if (geometry === undefined || geometry.geometryToken !== expectedGeometryToken) {
+    throw new Error('STALE_GRID: The Author grid geometry changed. Describe the grid again.');
+  }
+  const parsed = parseAuthorGridCell(cell);
+  const width = 1 / AUTHOR_GRID_SIZE;
+  const height = 1 / AUTHOR_GRID_SIZE;
+  const rect = { x: parsed.column * width, y: parsed.row * height, width, height };
+  return {
+    ...parsed,
+    rect,
+    center: { x: rect.x + width / 2, y: rect.y + height / 2 },
+    evidence: { cell: parsed.cell, geometryToken: geometry.geometryToken, snapshotId: geometry.snapshotId },
+  };
+}

package/src/web/lib/authorRegions.ts

@@ -0,0 +1,30 @@
+import type { AuthorNormalizedRect } from './authorViewportTypes.ts';
+
+export interface AuthorClientRect {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+/** Clamp a drag to the source element, including drags made in reverse. */
+export function normalizedAuthorRectangle(
+  bounds: AuthorClientRect,
+  drag: AuthorClientRect,
+): AuthorNormalizedRect | null {
+  const width = bounds.right - bounds.left;
+  const height = bounds.bottom - bounds.top;
+  if (![...Object.values(bounds), ...Object.values(drag)].every(Number.isFinite) || width <= 0 || height <= 0)
+    return null;
+  const left = Math.max(bounds.left, Math.min(drag.left, drag.right));
+  const right = Math.min(bounds.right, Math.max(drag.left, drag.right));
+  const top = Math.max(bounds.top, Math.min(drag.top, drag.bottom));
+  const bottom = Math.min(bounds.bottom, Math.max(drag.top, drag.bottom));
+  if (right <= left || bottom <= top) return null;
+  return {
+    x: (left - bounds.left) / width,
+    y: (top - bounds.top) / height,
+    width: (right - left) / width,
+    height: (bottom - top) / height,
+  };
+}

package/src/web/lib/authorViewportTypes.ts

@@ -0,0 +1,202 @@
+import type { AuthorJsonSchema } from '../../types/author.ts';
+import type { CsvDialect, DocumentFragment, StructuredDocumentFormat } from '../../types/structuredDocuments.ts';
+
+export type AuthorDocumentKind =
+  | 'text'
+  | 'markdown'
+  | 'slides'
+  | 'csv'
+  | 'pptx'
+  | 'xlsx'
+  | 'image'
+  | 'video'
+  | 'pdf'
+  | 'opaque';
+
+export interface AuthorDocumentInput {
+  path: string;
+  kind: AuthorDocumentKind;
+  content?: string;
+  mediaUrl?: string;
+  crop?: AuthorCrop;
+  title?: string;
+  sourceSha256?: string;
+  structuredFormat?: StructuredDocumentFormat;
+  csvDialect?: CsvDialect;
+  fragments?: readonly DocumentFragment[];
+  originalFragments?: readonly DocumentFragment[];
+}
+
+export interface AuthorAnnotation {
+  id: string;
+  kind: 'comment' | 'highlight';
+  body: string;
+  quote?: string;
+  startLine?: number;
+  endLine?: number;
+}
+
+export interface AuthorDraftRevision {
+  revision: number;
+  content: string;
+}
+
+/** A rectangle expressed relative to its source, not its current CSS size. */
+export interface AuthorNormalizedRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Legacy image crop shape. Coordinates are source-normalized for new records. */
+export type AuthorCrop = AuthorNormalizedRect;
+
+export interface AuthorTextRangeAnchor {
+  kind: 'text-range';
+  startOffset: number;
+  endOffset: number;
+  startLine: number;
+  endLine: number;
+}
+
+export interface AuthorCellAnchor {
+  kind: 'cell';
+  fragmentId: string;
+  location: string;
+  row?: number;
+  column?: number;
+  sheet?: string;
+}
+
+export interface AuthorSlideElementAnchor {
+  kind: 'slide-element';
+  fragmentId: string;
+  slide: number;
+  elementId?: string;
+  location: string;
+}
+
+export interface AuthorImageRectAnchor {
+  kind: 'image-rect';
+  rect: AuthorNormalizedRect;
+  naturalWidth: number;
+  naturalHeight: number;
+}
+
+export interface AuthorPdfPageRectAnchor {
+  kind: 'pdf-page-rect';
+  page: number;
+  rect: AuthorNormalizedRect;
+}
+
+export interface AuthorVideoTimeRectAnchor {
+  kind: 'video-time-rect';
+  timeSeconds: number;
+  rect: AuthorNormalizedRect;
+  frame?: number;
+  intrinsicWidth?: number;
+  intrinsicHeight?: number;
+}
+
+export type AuthorNativeAnchor =
+  | AuthorTextRangeAnchor
+  | AuthorCellAnchor
+  | AuthorSlideElementAnchor
+  | AuthorImageRectAnchor
+  | AuthorPdfPageRectAnchor
+  | AuthorVideoTimeRectAnchor;
+
+/** View state retained as capture evidence, never as mutation authority. */
+export interface AuthorViewportSnapshot {
+  width: number;
+  height: number;
+  originX?: number;
+  originY?: number;
+  scrollX?: number;
+  scrollY?: number;
+  zoom?: number;
+  page?: number;
+  slide?: number;
+  timeSeconds?: number;
+}
+
+export interface AuthorVoiceGridEvidence {
+  cell: string;
+  geometryToken: string;
+  snapshotId: string;
+}
+
+export type AuthorToolMode = 'select' | 'mark' | 'crop';
+
+export interface AuthorRegionCandidate {
+  documentPath: string;
+  revision: number;
+  sourceSha256?: string;
+  quote?: string;
+  anchor: AuthorNativeAnchor;
+  viewport: AuthorViewportSnapshot;
+  voiceGrid?: AuthorVoiceGridEvidence;
+  thumbnailUrl?: string;
+  createdAt: number;
+}
+
+export interface AuthorRegionDraft {
+  id: string;
+  documentPath: string;
+  revision: number;
+  sourceSha256?: string;
+  comment: string;
+  quote?: string;
+  anchor: AuthorNativeAnchor;
+  viewport: AuthorViewportSnapshot;
+  voiceGrid?: AuthorVoiceGridEvidence;
+  thumbnailUrl?: string;
+  createdAt: number;
+}
+
+/** A region paired with the stable request/draft number shown in the document. */
+export interface AuthorDisplayedRegion {
+  ordinal: number;
+  region: AuthorRegionDraft;
+}
+export type AuthorRequestStatus = 'REQUESTED' | 'CHANGING' | 'CHANGED' | 'COMPLETE' | 'FAILED' | 'CANCELLED';
+
+export interface AuthorRequestRecord {
+  id: string;
+  captureId?: string;
+  documentPath: string;
+  requestText: string;
+  regions: readonly AuthorRegionDraft[];
+  pendingRegions?: readonly AuthorRegionDraft[];
+  status: AuthorRequestStatus;
+  currentOperation?: string;
+  before?: string;
+  after?: string;
+  error?: string;
+  createdAt: number;
+  updatedAt: number;
+  revision: number;
+  sourceSha256?: string;
+}
+
+export interface AuthorFocusedDocument {
+  path: string;
+  generation: number;
+  revision: number;
+  sourceSha256?: string;
+  focusedAt: number;
+}
+
+export interface AuthorTrustedTool {
+  name: string;
+  label?: string;
+  description: string;
+  inputSchema: AuthorJsonSchema;
+  execute(input: unknown, signal: AbortSignal): Promise<unknown>;
+}
+
+export interface AuthorTrustedProfile {
+  id: string;
+  tools: readonly AuthorTrustedTool[];
+}

package/src/web/lib/describeAuthorToolsToolRender.ts

@@ -0,0 +1,20 @@
+import type { MessageLine } from '@agimon-ai/doompi-web-components';
+import { type ToolResultView, toolResultTextLines } from '@agimon-ai/doompi-web-contracts';
+
+export const describeAuthorToolsToolName = 'describe_author_tools';
+
+/** Lines the collapsed item shows before it expands. */
+export const describeAuthorToolsCollapsedLines = 8;
+
+export function describeAuthorToolsCallSummary(_args: Readonly<Record<string, unknown>>): string {
+  return '';
+}
+
+/**
+ * The body as toned lines: what the result's details say, or its text. Pure,
+ * so a unit test can pin it without a DOM; the item decides how many to show.
+ */
+export function describeAuthorToolsResultLines(result: ToolResultView | null): MessageLine[] {
+  if (result === null) return [];
+  return toolResultTextLines(result.content).map((text) => ({ text, tone: 'dim' }));
+}

package/src/web/lib/useAuthorToolsToolRender.ts

@@ -0,0 +1,20 @@
+import type { MessageLine } from '@agimon-ai/doompi-web-components';
+import { type ToolResultView, toolResultTextLines } from '@agimon-ai/doompi-web-contracts';
+
+export const useAuthorToolsToolName = 'use_author_tools';
+
+/** Lines the collapsed item shows before it expands. */
+export const useAuthorToolsCollapsedLines = 8;
+
+export function useAuthorToolsCallSummary(args: Readonly<Record<string, unknown>>): string {
+  return typeof args.name === 'string' ? args.name : '';
+}
+
+/**
+ * The body as toned lines: what the result's details say, or its text. Pure,
+ * so a unit test can pin it without a DOM; the item decides how many to show.
+ */
+export function useAuthorToolsResultLines(result: ToolResultView | null): MessageLine[] {
+  if (result === null) return [];
+  return toolResultTextLines(result.content).map((text) => ({ text, tone: 'dim' }));
+}