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

package/src/exports/webClient.ts

@@ -0,0 +1,76 @@
+export { AuthorClientBroker } from '../web/api/authorBroker.ts';
+export { authorFileTab } from '../web/components/AuthorDocumentPanel.tsx';
+export { AuthorRuntime, AUTHOR_RUNTIME_BINDING_IDS } from '../web/api/authorRuntime.ts';
+export { AUTHOR_TRUSTED_PROFILES } from '../web/stores/authorProfiles.ts';
+export {
+  AUTHOR_CAPTURE_MAX_BYTES,
+  AUTHOR_CAPTURE_MAX_DIMENSION,
+  AUTHOR_COMMENT_MAX_BYTES,
+  AUTHOR_PACKET_MAX_BYTES,
+  AUTHOR_QUOTE_MAX_BYTES,
+  attachAuthorCapture,
+  authorCaptureContext,
+  createAuthorCapturePacket,
+  imageCaptureProvider,
+  multiRegionCaptureProvider,
+} from '../web/stores/authorCapture.ts';
+export type {
+  AuthorCapturePacket,
+  AuthorCapturePacketRegion,
+  AuthorCaptureProvider,
+} from '../web/stores/authorCapture.ts';
+export {
+  AUTHOR_GRID_COLUMNS,
+  AUTHOR_GRID_SIZE,
+  authorGrid,
+  authorGridGeometry,
+  clearAuthorGridGeometry,
+  parseAuthorGridCell,
+  resolveAuthorGridCell,
+  updateAuthorGridGeometry,
+} from '../web/lib/authorGrid.ts';
+export type { AuthorGridCellResolution, AuthorGridGeometry } from '../web/lib/authorGrid.ts';
+export {
+  addAuthorAnnotation,
+  addAuthorRegion,
+  authorDocument,
+  authorSessionWorkspace,
+  authorWorkspace,
+  dropAuthorSession,
+  focusAuthorDocument,
+  normalizeAuthorPath,
+  putAuthorDocument,
+  putAuthorRequest,
+  releaseAuthorDocumentFocus,
+  removeAuthorRegion,
+  requestAuthorSave,
+  reviseAuthorDocument,
+  setAuthorCrop,
+  syncAuthorDocumentFocus,
+  updateAuthorRegionComment,
+  updateAuthorRequest,
+} from '../web/stores/authorWorkspaceStore.ts';
+export { webPlugin } from '../web/index.ts';
+export type {
+  AuthorAnnotation,
+  AuthorCellAnchor,
+  AuthorCrop,
+  AuthorDocumentInput,
+  AuthorDocumentKind,
+  AuthorDraftRevision,
+  AuthorFocusedDocument,
+  AuthorImageRectAnchor,
+  AuthorNativeAnchor,
+  AuthorNormalizedRect,
+  AuthorPdfPageRectAnchor,
+  AuthorRegionDraft,
+  AuthorRequestRecord,
+  AuthorRequestStatus,
+  AuthorSlideElementAnchor,
+  AuthorTextRangeAnchor,
+  AuthorTrustedProfile,
+  AuthorTrustedTool,
+  AuthorVideoTimeRectAnchor,
+  AuthorViewportSnapshot,
+  AuthorVoiceGridEvidence,
+} from '../web/lib/authorViewportTypes.ts';

package/src/prompts/doompi-use-author/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: doompi-use-author
+description: 'Use @agimon-ai/doompi-author: Visual steering workspace for focused document review and bounded authoring'
+---
+
+# Use Author
+
+Read the package [README](../../../README.md) for its exact installation, command, configuration, and behavior.
+
+## Guidance
+
+- Use `/doom-author` as the package's primary Pi entrypoint.
+- Treat the package README and its linked resources as the source of truth for package-specific behavior.
+- Do not require DoomPi Help for runtime activation. Help only makes this package guidance discoverable while the minor mode is active.
+- Autonomous Voice coordinates are evidence, not mutation authority. Call `author_describe_grid`, then `author_resolve_grid_cell` with the returned geometry token and the user's verbatim instruction.
+- Mutate only through the resulting `regionId` with `author_apply_region`, passing the expected revision and source digest. Apply multi-region requests sequentially and use the revision returned by each successful mutation for the next region. On `STALE_GRID`, `STALE_DOCUMENT`, or `STALE_REGION`, describe and resolve again.
+- Text, Markdown, editable cells, slide text, and image crop support mutation. PDF and video regions are capture-only.

package/src/types/author.ts

@@ -0,0 +1,45 @@
+export const AUTHOR_MODE_ID = 'author' as const;
+export const OPEN_AUTHORING_FILE_TOOL_NAME = 'open_authoring_file' as const;
+
+export type AuthorModeActivation = 'inactive' | 'active';
+
+export interface AuthorModeSnapshot {
+  activation: AuthorModeActivation;
+  catalogToken: string;
+  capabilityCount: number;
+}
+
+export type AuthorJsonSchema = Readonly<Record<string, unknown>>;
+
+export interface AuthorViewportCapabilityDescriptor {
+  name: string;
+  label: string;
+  description: string;
+  inputSchema: AuthorJsonSchema;
+}
+
+export interface AuthorViewportCapability extends AuthorViewportCapabilityDescriptor {
+  execute(argumentsValue: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
+}
+
+export interface AuthorViewportCatalogSnapshot {
+  catalogToken: string;
+  tools: AuthorViewportCapabilityDescriptor[];
+}
+
+export interface AuthorOpenFileResult {
+  path: string;
+  byteLength: number;
+}
+
+export interface UseAuthorToolInput {
+  catalogToken: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface AuthorToolResult {
+  catalogToken: string;
+  name: string;
+  result: unknown;
+}

package/src/types/structuredDocuments.ts

@@ -0,0 +1,63 @@
+export type StructuredDocumentFormat = 'markdown-slides' | 'csv' | 'pptx' | 'xlsx';
+
+export interface DocumentManifest {
+  format: StructuredDocumentFormat;
+  sourceDigest: string;
+  byteLength: number;
+  fragmentCount: number;
+  metadata: Record<string, string | number | boolean>;
+}
+
+export interface DocumentFragment {
+  id: string;
+  kind: 'slide' | 'cell' | 'text-run';
+  text: string;
+  readOnly?: boolean;
+  location: string;
+}
+
+export interface DocumentRenderModel {
+  format: StructuredDocumentFormat;
+  blocks: Array<{ id: string; text: string; readOnly: boolean }>;
+}
+
+export interface DocumentOperation {
+  fragmentId: string;
+  replacement: string;
+}
+
+export interface DocumentOperationLogEntry extends DocumentOperation {
+  previous: string;
+}
+
+export interface DocumentPreflightIssue {
+  code: string;
+  message: string;
+  fragmentId?: string;
+}
+
+export interface DocumentPreflightReport {
+  accepted: boolean;
+  digest: string;
+  sourceDigest: string;
+  operations: DocumentOperationLogEntry[];
+  issues: DocumentPreflightIssue[];
+}
+
+export interface ParsedStructuredDocument {
+  manifest: DocumentManifest;
+  fragments: DocumentFragment[];
+  renderModel: DocumentRenderModel;
+}
+
+export interface SerializedStructuredDocument {
+  bytes: Uint8Array;
+  operationLog: DocumentOperationLogEntry[];
+  manifest: DocumentManifest;
+}
+
+export interface CsvDialect {
+  delimiter: ',' | ';' | '\t' | '|';
+  quote: '"' | "'";
+  recordDelimiter: '\n' | '\r\n';
+}

package/src/types/webAuthor.ts

@@ -0,0 +1,85 @@
+import type { AuthorViewportCapabilityDescriptor } from './author.ts';
+
+export const authorChannelType = 'author_webmcp';
+
+export interface AuthorRegisterMessage {
+  kind: 'register';
+  generation: number;
+}
+
+export interface AuthorReleaseMessage {
+  kind: 'release';
+  generation: number;
+}
+export interface AuthorCatalogMessage {
+  kind: 'catalog';
+  generation: number;
+  ownerToken: string;
+  tools: AuthorViewportCapabilityDescriptor[];
+}
+
+export interface AuthorResultMessage {
+  kind: 'result';
+  generation: number;
+  ownerToken: string;
+  catalogToken: string;
+  requestId: string;
+  result: unknown;
+}
+
+export interface AuthorCancelledMessage {
+  kind: 'cancelled';
+  generation: number;
+  ownerToken: string;
+  catalogToken: string;
+  requestId: string;
+}
+
+export type AuthorBrowserMessage =
+  | AuthorRegisterMessage
+  | AuthorReleaseMessage
+  | AuthorCatalogMessage
+  | AuthorResultMessage
+  | AuthorCancelledMessage;
+
+export interface AuthorAcceptedMessage {
+  kind: 'accepted';
+  generation: number;
+  ownerToken: string;
+  catalogToken?: string;
+  leaseMs: number;
+}
+
+export interface AuthorRequestMessage {
+  kind: 'request';
+  generation: number;
+  ownerToken: string;
+  catalogToken: string;
+  requestId: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface AuthorCancelMessage {
+  kind: 'cancel';
+  generation: number;
+  ownerToken: string;
+  catalogToken: string;
+  requestId: string;
+}
+
+export interface AuthorRejectedMessage {
+  kind: 'rejected';
+  reason: string;
+}
+
+export type AuthorHubMessage =
+  | AuthorAcceptedMessage
+  | AuthorRequestMessage
+  | AuthorCancelMessage
+  | AuthorRejectedMessage;
+
+export interface AuthorWebView {
+  activation: 'inactive' | 'active';
+  capabilityCount: number;
+}

package/src/web/api/authorBroker.ts

@@ -0,0 +1,14 @@
+import type { ModelContext } from '@agimon-ai/doompi-web-contracts';
+
+/** Client-side broker transport. Calls always cross Model Context's execution boundary. */
+export class AuthorClientBroker {
+  readonly #modelContext: ModelContext;
+
+  constructor(modelContext: ModelContext) {
+    this.#modelContext = modelContext;
+  }
+
+  execute(name: string, input: unknown, signal: AbortSignal): Promise<unknown> {
+    return this.#modelContext.executeTool(name, JSON.stringify(input), { signal });
+  }
+}

package/src/web/api/authorBrowserBridge.ts

@@ -0,0 +1,225 @@
+import type { WebPluginRuntime } from '@agimon-ai/doompi-web-contracts';
+import { Store } from '@tanstack/store';
+import type { AuthorHubMessage } from '../../types/webAuthor.ts';
+import { authorChannelType } from '../../types/webAuthor.ts';
+import { AuthorRuntime } from './authorRuntime.ts';
+import type { AuthorTrustedProfile } from '../lib/authorViewportTypes.ts';
+
+interface ActiveViewport {
+  sessionId: string;
+  generation: number;
+  profiles: readonly AuthorTrustedProfile[];
+  release: () => void;
+  ownerToken?: string;
+  catalogToken?: string;
+}
+
+class AuthorBrowserBridge {
+  readonly #host: WebPluginRuntime;
+  readonly #runtime: AuthorRuntime;
+  readonly #pending = new Map<string, AbortController>();
+  #active: ActiveViewport | undefined;
+  #generation = 0;
+  #disposed = false;
+  readonly #releaseConnected: () => void;
+  #leaseTimer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(host: WebPluginRuntime) {
+    this.#host = host;
+    this.#runtime = new AuthorRuntime(host);
+    this.#releaseConnected = host.onHubConnected(() => {
+      if (this.#active !== undefined) {
+        this.#active.ownerToken = undefined;
+        this.#active.catalogToken = undefined;
+      }
+      this.#register();
+    });
+  }
+
+  async focus(sessionId: string, profiles: readonly AuthorTrustedProfile[]): Promise<() => void> {
+    if (this.#disposed) throw new Error('Author browser bridge is disposed');
+    const generation = ++this.#generation;
+    const release = await this.#runtime.replaceProfiles(profiles);
+    if (this.#disposed || generation !== this.#generation) {
+      release();
+      return () => undefined;
+    }
+    this.#clearActive();
+    this.#active = { sessionId, generation, profiles, release };
+    this.#register();
+    return () => {
+      if (this.#active?.generation !== generation) return;
+      this.#clearActive();
+      this.#generation += 1;
+    };
+  }
+
+  drop(sessionId: string): void {
+    if (this.#active?.sessionId !== sessionId) return;
+    this.#clearActive();
+    this.#generation += 1;
+  }
+
+  apply(sessionId: string, message: AuthorHubMessage): void {
+    const active = this.#active;
+    if (active === undefined || active.sessionId !== sessionId || message.kind === 'rejected') return;
+    if (
+      message.generation !== active.generation ||
+      (message.ownerToken !== active.ownerToken && active.ownerToken !== undefined)
+    )
+      return;
+    if (message.kind === 'accepted') {
+      active.ownerToken = message.ownerToken;
+      clearTimeout(this.#leaseTimer);
+      this.#leaseTimer = setTimeout(() => this.#register(), Math.max(1000, Math.floor(message.leaseMs / 2)));
+      if (message.catalogToken === undefined) this.#sendCatalog(active);
+      else active.catalogToken = message.catalogToken;
+      return;
+    }
+    if (message.catalogToken !== active.catalogToken) return;
+    if (message.kind === 'cancel') {
+      this.#pending.get(message.requestId)?.abort(new Error('Author tool request cancelled'));
+      return;
+    }
+    if (message.kind !== 'request' || this.#pending.has(message.requestId)) return;
+    const controller = new AbortController();
+    this.#pending.set(message.requestId, controller);
+    void this.#runtime
+      .execute(message.name, message.arguments, controller.signal)
+      .then((result) => {
+        if (!this.#current(active, message.requestId, controller)) return;
+        if (controller.signal.aborted) this.#sendCancelled(active, message.requestId);
+        else
+          this.#send(active.sessionId, {
+            kind: 'result',
+            generation: active.generation,
+            ownerToken: active.ownerToken!,
+            catalogToken: active.catalogToken!,
+            requestId: message.requestId,
+            result,
+          });
+      })
+      .catch((error: unknown) => {
+        if (!this.#current(active, message.requestId, controller)) return;
+        if (controller.signal.aborted) this.#sendCancelled(active, message.requestId);
+        else {
+          const messageText = error instanceof Error ? error.message : String(error);
+          const code = /^([A-Z][A-Z_]+):/u.exec(messageText)?.[1] ?? 'AUTHOR_TOOL_ERROR';
+          this.#send(active.sessionId, {
+            kind: 'result',
+            generation: active.generation,
+            ownerToken: active.ownerToken!,
+            catalogToken: active.catalogToken!,
+            requestId: message.requestId,
+            result: { error: { code, message: messageText } },
+          });
+        }
+      })
+      .finally(() => {
+        if (this.#pending.get(message.requestId) === controller) this.#pending.delete(message.requestId);
+      });
+  }
+
+  activeView(sessionId: string): { activation: 'inactive' | 'active'; capabilityCount: number } {
+    const active = this.#active;
+    return active?.sessionId === sessionId && active.catalogToken !== undefined
+      ? {
+          activation: 'active',
+          capabilityCount: active.profiles.reduce((count, profile) => count + profile.tools.length, 0),
+        }
+      : { activation: 'inactive', capabilityCount: 0 };
+  }
+
+  dispose(): void {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    clearTimeout(this.#leaseTimer);
+    this.#releaseConnected();
+    this.#clearActive();
+    this.#runtime.dispose();
+  }
+
+  #register(): void {
+    const active = this.#active;
+    if (active !== undefined) this.#send(active.sessionId, { kind: 'register', generation: active.generation });
+  }
+
+  #sendCatalog(active: ActiveViewport): void {
+    this.#send(active.sessionId, {
+      kind: 'catalog',
+      generation: active.generation,
+      ownerToken: active.ownerToken!,
+      tools: active.profiles.flatMap((profile) =>
+        profile.tools.map((tool) => ({
+          name: tool.name,
+          label: tool.label ?? tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+        })),
+      ),
+    });
+  }
+
+  #sendCancelled(active: ActiveViewport, requestId: string): void {
+    this.#send(active.sessionId, {
+      kind: 'cancelled',
+      generation: active.generation,
+      ownerToken: active.ownerToken!,
+      catalogToken: active.catalogToken!,
+      requestId,
+    });
+  }
+
+  #send(sessionId: string, payload: Record<string, unknown>): void {
+    this.#host.sendHubFrame({ type: authorChannelType, sessionId, payload });
+  }
+
+  #current(active: ActiveViewport, requestId: string, controller: AbortController): boolean {
+    return this.#active === active && this.#pending.get(requestId) === controller;
+  }
+
+  #clearActive(): void {
+    clearTimeout(this.#leaseTimer);
+    this.#leaseTimer = undefined;
+    const active = this.#active;
+    if (active !== undefined) {
+      this.#send(active.sessionId, { kind: 'release', generation: active.generation });
+      active.release();
+    }
+    this.#active = undefined;
+    for (const controller of this.#pending.values()) controller.abort(new Error('Author viewport changed'));
+    this.#pending.clear();
+  }
+}
+
+const authorBridgeRuntime = new Store<AuthorBrowserBridge | undefined>(undefined);
+
+export function startAuthorBrowserBridge(runtime: WebPluginRuntime): () => void {
+  authorBridgeRuntime.state?.dispose();
+  const next = new AuthorBrowserBridge(runtime);
+  authorBridgeRuntime.setState(() => next);
+  return () => {
+    if (authorBridgeRuntime.state !== next) return;
+    next.dispose();
+    authorBridgeRuntime.setState(() => undefined);
+  };
+}
+
+export async function focusAuthorViewport(
+  sessionId: string,
+  profiles: readonly AuthorTrustedProfile[],
+): Promise<() => void> {
+  return (await authorBridgeRuntime.state?.focus(sessionId, profiles)) ?? (() => undefined);
+}
+
+export function applyAuthorHubMessage(sessionId: string, message: AuthorHubMessage): void {
+  authorBridgeRuntime.state?.apply(sessionId, message);
+}
+
+export function dropAuthorViewportSession(sessionId: string): void {
+  authorBridgeRuntime.state?.drop(sessionId);
+}
+
+export function authorBridgeView(sessionId: string): { activation: 'inactive' | 'active'; capabilityCount: number } {
+  return authorBridgeRuntime.state?.activeView(sessionId) ?? { activation: 'inactive', capabilityCount: 0 };
+}