@sudodevstudio/astro-ai 0.1.0

package/src/resolver/types.ts

@@ -0,0 +1,47 @@
+import type {
+  DataProvenance,
+  EditableProp,
+  RepeatContext,
+  SourceKind,
+  SourceLocation,
+} from '../shared/selection-context.js';
+
+export type SourceRange = {
+  start: number;
+  end: number;
+};
+
+export type SourceProp = EditableProp & {
+  range: SourceRange;
+  syntax: 'quoted' | 'expression' | 'shorthand';
+};
+
+export type SourceNodeRecord = {
+  nodeId: string;
+  filePath: string;
+  sourceLanguage: 'astro' | 'jsx' | 'tsx';
+  sourceHash: string;
+  structuralPath: string;
+  source: SourceLocation;
+  range: SourceRange;
+  openingRange: SourceRange;
+  textRange?: SourceRange;
+  textValue?: string;
+  tagName?: string;
+  componentName?: string;
+  parentNodeId?: string;
+  siblingGroupId?: string;
+  previousSiblingId?: string;
+  nextSiblingId?: string;
+  parentComponents: Array<{
+    name: string;
+    source?: SourceLocation;
+  }>;
+  literalProps: SourceProp[];
+  sourceKind: SourceKind;
+  dataProvenance: DataProvenance;
+  repeatContext?: RepeatContext;
+  hydratedIsland: boolean;
+  instrumentable: boolean;
+  selfClosing: boolean;
+};

package/src/shared/protocol.ts

@@ -0,0 +1,181 @@
+import type { SelectionContext } from './selection-context.js';
+import type { SourceInsertionZone } from './selection-context.js';
+import type { DeterministicVisualCommand } from '../visual/commands.js';
+import type {
+  PatchHistoryState,
+  PatchTransactionSummary,
+} from '../visual/patch-transactions.js';
+
+export const PROTOCOL_VERSION = 2 as const;
+
+export const CLIENT_EVENTS = {
+  ready: 'astro-ai:client-ready',
+  inspect: 'astro-ai:inspect',
+  execute: 'astro-ai:execute',
+  undo: 'astro-ai:undo',
+  redo: 'astro-ai:redo',
+  agentInstruction: 'astro-ai:agent-instruction',
+  agentCancel: 'astro-ai:agent-cancel',
+  sessionClose: 'astro-ai:session-close',
+  insertionZones: 'astro-ai:insertion-zones',
+} as const;
+
+/**
+ * Identifies one chat window's conversation. Every window keeps its own turn
+ * history and provider workspace; source history stays shared across windows
+ * because all windows edit the same project files.
+ */
+export const DEFAULT_SESSION_ID = 'default';
+
+export const SERVER_EVENTS = {
+  ready: 'astro-ai:server-ready',
+  selection: 'astro-ai:selection',
+  operation: 'astro-ai:operation',
+  history: 'astro-ai:history',
+  error: 'astro-ai:error',
+  agentEvent: 'astro-ai:agent-event',
+  insertionZones: 'astro-ai:insertion-zones-result',
+} as const;
+
+export type ClientReadyMessage = {
+  protocolVersion: typeof PROTOCOL_VERSION;
+  route: string;
+  pendingAgentRequestIds?: string[];
+  /** Chat windows the page still has open; idle server sessions outside this list are released. */
+  activeSessionIds?: string[];
+};
+
+export type ServerReadyMessage = {
+  protocolVersion: typeof PROTOCOL_VERSION;
+  history: PatchHistoryState;
+  agent: {
+    provider: string;
+    available: boolean;
+    authenticated: boolean;
+    message: string;
+  };
+};
+
+export type InspectSelectionMessage = {
+  requestId: string;
+  nodeId: string;
+  route: string;
+};
+
+export type ExecuteVisualCommandMessage = {
+  requestId: string;
+  command: DeterministicVisualCommand;
+};
+
+export type HistoryCommandMessage = {
+  requestId: string;
+};
+
+export type AgentSelectionReference = {
+  nodeId: string;
+  route: string;
+};
+
+export type AgentExternalContext = {
+  kind: 'error' | 'audit';
+  title: string;
+  message: string;
+  file?: string;
+  line?: number;
+};
+
+export type AgentRequestMode = 'auto' | 'answer';
+
+export type AgentFileAttachment = {
+  name: string;
+  content: string;
+  size: number;
+  mediaType?: string;
+  kind?: 'text' | 'image';
+  encoding?: 'utf8' | 'base64';
+};
+
+export type AgentInstructionMessage = {
+  requestId: string;
+  sessionId?: string;
+  instruction: string;
+  mode?: AgentRequestMode;
+  attachments?: AgentSelectionReference[];
+  locked?: boolean;
+  files?: AgentFileAttachment[];
+  externalContext?: AgentExternalContext;
+};
+
+export type AgentCancelMessage = {
+  requestId: string;
+};
+
+export type AgentSessionClosedMessage = {
+  sessionId: string;
+};
+
+export type InsertionZonesRequestMessage = { requestId: string; route: string };
+export type InsertionZonesResolvedMessage = { requestId: string; zones: SourceInsertionZone[] };
+
+export type AgentOperationState =
+  | 'planning'
+  | 'queued'
+  | 'reading'
+  | 'editing'
+  | 'validation'
+  | 'diagnostics'
+  | 'tool'
+  | 'completion'
+  | 'cancellation'
+  | 'failure';
+
+export type AgentOperationEvent = {
+  requestId: string;
+  sessionId?: string;
+  state: AgentOperationState;
+  message: string;
+  response?: string;
+  provider?: string;
+  transaction?: PatchTransactionSummary;
+};
+
+export type SelectionResolvedMessage = {
+  requestId: string;
+  context: SelectionContext;
+};
+
+export type OperationCompletedMessage = {
+  requestId: string;
+  transaction: PatchTransactionSummary;
+  history: PatchHistoryState;
+};
+
+export type HistoryChangedMessage = PatchHistoryState;
+
+export type VisualEditorErrorMessage = {
+  requestId?: string;
+  message: string;
+  fallbackEligible: boolean;
+};
+
+export type ClientToServerMessages = {
+  [CLIENT_EVENTS.ready]: ClientReadyMessage;
+  [CLIENT_EVENTS.inspect]: InspectSelectionMessage;
+  [CLIENT_EVENTS.execute]: ExecuteVisualCommandMessage;
+  [CLIENT_EVENTS.undo]: HistoryCommandMessage;
+  [CLIENT_EVENTS.redo]: HistoryCommandMessage;
+  [CLIENT_EVENTS.agentInstruction]: AgentInstructionMessage;
+  [CLIENT_EVENTS.agentCancel]: AgentCancelMessage;
+  [CLIENT_EVENTS.sessionClose]: AgentSessionClosedMessage;
+  [CLIENT_EVENTS.insertionZones]: InsertionZonesRequestMessage;
+};
+
+export type ServerToClientMessages = {
+  [SERVER_EVENTS.ready]: ServerReadyMessage;
+  [SERVER_EVENTS.selection]: SelectionResolvedMessage;
+  [SERVER_EVENTS.operation]: OperationCompletedMessage;
+  [SERVER_EVENTS.history]: HistoryChangedMessage;
+  [SERVER_EVENTS.error]: VisualEditorErrorMessage;
+  [SERVER_EVENTS.agentEvent]: AgentOperationEvent;
+  [SERVER_EVENTS.insertionZones]: InsertionZonesResolvedMessage;
+};

package/src/shared/selection-context.ts

@@ -0,0 +1,91 @@
+export type SourcePosition = {
+  line: number;
+  column: number;
+  offset: number;
+};
+
+export type SourceLocation = {
+  file: string;
+  start: SourcePosition;
+  end: SourcePosition;
+};
+
+export type SourceKind =
+  | 'literal-source'
+  | 'local-variable'
+  | 'prop'
+  | 'external'
+  | 'repeated-template'
+  | 'generated-unknown'
+  | 'component'
+  | 'hydrated-island';
+
+export type DataProvenance = {
+  kind: 'literal' | 'local' | 'prop' | 'import' | 'external' | 'unknown';
+  description: string;
+  symbol?: string;
+  declaredAt?: SourceLocation;
+  readOnly: boolean;
+  sourceType?: 'api' | 'action' | 'content-collection' | 'graphql' | 'import';
+  sourceFile?: string;
+};
+
+export type RepeatContext = {
+  kind: 'map';
+  description: string;
+  source: SourceLocation;
+  affectsAllInstances: true;
+};
+
+export type EditableProp = {
+  name: string;
+  type: 'string' | 'number' | 'boolean';
+  value: string | number | boolean;
+  allowedValues?: Array<string | number | boolean>;
+  control?: 'text' | 'number' | 'boolean' | 'enum' | 'design-token';
+};
+
+export type VisualCapabilities = {
+  editableText: boolean;
+  movable: boolean;
+  reorderable: boolean;
+  removable: boolean;
+  editableProps: EditableProp[];
+  allowedParentSlots: string[];
+  sourceKind: SourceKind;
+  dataProvenance: DataProvenance;
+  repeatContext?: RepeatContext;
+  reorderTargets: {
+    previous?: string;
+    next?: string;
+  };
+};
+
+export type SelectedSourceNode = {
+  nodeId: string;
+  tagName?: string;
+  componentName?: string;
+  literalText?: string;
+  source: SourceLocation;
+};
+
+export type SelectionContext = {
+  route: string;
+  selectedNode: SelectedSourceNode;
+  parentComponents: Array<{
+    name: string;
+    source?: SourceLocation;
+  }>;
+  capabilities: VisualCapabilities;
+  relevantFiles: string[];
+  skillFiles: string[];
+};
+
+export type SourceInsertionZone = {
+  id: string;
+  file: string;
+  offset: number;
+  parentNodeId?: string;
+  slot?: string;
+  acceptedChildTypes: string[];
+};

package/src/shared/visual-components.ts

@@ -0,0 +1,16 @@
+export type VisualPropDefinition = {
+  control: 'text' | 'number' | 'boolean' | 'enum' | 'design-token';
+  values?: Array<string | number | boolean>;
+};
+
+export type VisualSlotDefinition = {
+  name: string;
+  accepts?: string[];
+};
+
+export type VisualComponentDefinition = {
+  name: string;
+  props?: Record<string, VisualPropDefinition>;
+  slots?: VisualSlotDefinition[];
+  layout?: 'flow' | 'flex' | 'grid' | 'freeform';
+};

package/src/toolbar/action-model.ts

@@ -0,0 +1,67 @@
+import type { SelectionContext } from '../shared/selection-context.js';
+
+export type ContextualActionId = 'click' | 'edit' | 'props' | 'move' | 'remove' | 'ask-ai' | 'source';
+
+export type ContextualAction = {
+  id: ContextualActionId;
+  label: string;
+};
+
+export type SelectionAttachment = {
+  nodeId: string;
+  route: string;
+  label: string;
+  source: SelectionContext['selectedNode']['source'];
+  sourceKind: SelectionContext['capabilities']['sourceKind'];
+  provenance: SelectionContext['capabilities']['dataProvenance'];
+  repeatContext?: SelectionContext['capabilities']['repeatContext'];
+  parentComponents: SelectionContext['parentComponents'];
+};
+
+export function contextualActions(context: SelectionContext): ContextualAction[] {
+  // Selection mode swallows page clicks, so driving the app to the state you
+  // want to edit needs an explicit way through. It leads because it changes no
+  // source and is often the first thing you do on a selected element.
+  const actions: ContextualAction[] = [{ id: 'click', label: 'Click' }];
+  if (context.capabilities.editableText) actions.push({ id: 'edit', label: 'Edit' });
+  if (context.capabilities.editableProps.length > 0) actions.push({ id: 'props', label: 'Props' });
+  if (context.capabilities.movable || context.capabilities.reorderable) {
+    actions.push({ id: 'move', label: 'Move' });
+  }
+  if (context.capabilities.removable) actions.push({ id: 'remove', label: 'Remove' });
+  actions.push({ id: 'ask-ai', label: 'Ask AI' }, { id: 'source', label: 'Source' });
+  return actions;
+}
+
+export function createSelectionAttachment(context: SelectionContext): SelectionAttachment {
+  const attachment: SelectionAttachment = {
+    nodeId: context.selectedNode.nodeId,
+    route: context.route,
+    label: context.selectedNode.componentName ?? context.selectedNode.tagName ?? 'Astro node',
+    source: clone(context.selectedNode.source),
+    sourceKind: context.capabilities.sourceKind,
+    provenance: clone(context.capabilities.dataProvenance),
+    parentComponents: clone(context.parentComponents),
+  };
+  if (context.capabilities.repeatContext !== undefined) {
+    attachment.repeatContext = clone(context.capabilities.repeatContext);
+  }
+  return attachment;
+}
+
+export function middleTruncatePath(path: string, maxLength = 42): string {
+  if (path.length <= maxLength) return path;
+  const basename = path.slice(path.lastIndexOf('/') + 1);
+  if (basename.length < maxLength - 2) {
+    const prefixLength = maxLength - basename.length - 1;
+    return `${path.slice(0, prefixLength)}…${basename}`;
+  }
+  const available = Math.max(2, maxLength - 1);
+  const left = Math.ceil(available / 2);
+  const right = Math.floor(available / 2);
+  return `${path.slice(0, left)}…${path.slice(-right)}`;
+}
+
+function clone<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}

package/src/toolbar/app.ts

@@ -0,0 +1,294 @@
+import { defineToolbarApp } from 'astro/toolbar';
+
+import {
+  CLIENT_EVENTS,
+  PROTOCOL_VERSION,
+  SERVER_EVENTS,
+  type AgentOperationEvent,
+  type ClientReadyMessage,
+  type HistoryChangedMessage,
+  type InsertionZonesResolvedMessage,
+  type OperationCompletedMessage,
+  type SelectionResolvedMessage,
+  type ServerReadyMessage,
+  type VisualEditorErrorMessage,
+} from '../shared/protocol.js';
+import type { DeterministicVisualCommand } from '../visual/commands.js';
+import { createChatDrawerStyle } from './chat-drawer.js';
+import { ChatWindowManager } from './chat-windows.js';
+import { DiagnosticActionBridge } from './diagnostic-actions.js';
+import { SelectionOverlay } from './overlay.js';
+
+const APP_OPEN_KEY = 'astro-ai:app-open';
+
+export default defineToolbarApp({
+  init(canvas, app, server) {
+    let disposed = false;
+    let restoringOpenState = readSession(APP_OPEN_KEY) === 'true';
+    const pendingInspectRequests = new Map<string, string>();
+    let insertionZonesRequestId: string | undefined;
+    let overlay: SelectionOverlay;
+    const windows = new ChatWindowManager({
+      onSubmit({ requestId, sessionId, instruction, mode, attachments, locked, files, externalContext }) {
+        server.send(CLIENT_EVENTS.agentInstruction, {
+          requestId,
+          sessionId,
+          instruction,
+          mode,
+          ...(attachments === undefined
+            ? {}
+            : {
+                attachments: attachments.map(({ nodeId, route }) => ({ nodeId, route })),
+              }),
+          ...(locked === true ? { locked: true } : {}),
+          ...(files === undefined ? {} : { files }),
+          ...(externalContext === undefined ? {} : { externalContext }),
+        });
+        windows.noticeFor(sessionId, 'AI agent operation started…');
+      },
+      onCancel(requestId) {
+        server.send(CLIENT_EVENTS.agentCancel, { requestId });
+      },
+      onUndo() {
+        windows.broadcastNotice('Undoing the last source transaction…');
+        server.send(CLIENT_EVENTS.undo, { requestId: createRequestId() });
+      },
+      onRedo() {
+        windows.broadcastNotice('Redoing the source transaction…');
+        server.send(CLIENT_EVENTS.redo, { requestId: createRequestId() });
+      },
+      onSessionClose(sessionId) {
+        server.send(CLIENT_EVENTS.sessionClose, { sessionId });
+      },
+      onEmpty() {
+        app.toggleState({ state: false });
+      },
+      onSelectionPaused(paused) {
+        if (paused) {
+          overlay.disable();
+          windows.broadcastNotice('Selection mode paused while every chat is minimized.');
+        } else {
+          overlay.enable();
+          overlay.start();
+          windows.broadcastNotice('Click to select · Shift-click to add · drag to marquee');
+          requestInsertionZones();
+        }
+      },
+    });
+
+    overlay = new SelectionOverlay({
+      onInspect(nodeId) {
+        const requestId = createRequestId();
+        pendingInspectRequests.set(requestId, nodeId);
+        windows.broadcastNotice('Resolving source capabilities…');
+        server.send(CLIENT_EVENTS.inspect, {
+          requestId,
+          nodeId,
+          route: window.location.pathname,
+        });
+      },
+      onActiveChange() {},
+      onCommand(command) {
+        execute(command);
+      },
+      onAskAI(contexts, elements) {
+        windows.openWithSelections(contexts, elements);
+      },
+      onClear() {
+        windows.broadcastNotice('Click to select · Shift-click to add · drag to marquee');
+      },
+      onSelectionChange(contexts, elements) {
+        windows.setCurrentSelections(contexts, elements);
+        if (contexts.length > 1) {
+          windows.broadcastNotice(`${contexts.length} source-backed elements selected.`);
+        }
+      },
+      onSelectionAnchorChange(rect) {
+        windows.setSelectionAnchor(rect);
+      },
+    });
+    const diagnosticActions = new DiagnosticActionBridge({
+      onFix(context) {
+        overlay.clearSelection();
+        app.toggleState({ state: true });
+        window.setTimeout(() => windows.openWithExternalContext(context), 0);
+      },
+    });
+
+    const drawerStyle = createChatDrawerStyle();
+    canvas.replaceChildren(drawerStyle, windows.element);
+    windows.hideAll(false);
+
+    /**
+     * Astro's app canvas rewrites its own shadow root in `connectedCallback`,
+     * and a client-side navigation re-appends the toolbar to the swapped body,
+     * which reconnects the canvas and throws away everything rendered into it.
+     * The chat windows survive as objects, so they only need remounting.
+     */
+    function ensureMounted(): void {
+      if (windows.element.parentNode === canvas) return;
+      canvas.append(drawerStyle, windows.element);
+    }
+
+    app.onToggled(({ state }) => {
+      writeSession(APP_OPEN_KEY, String(state));
+      if (state) {
+        ensureMounted();
+        overlay.enable();
+        overlay.start();
+        // Astro re-applies app status when the toolbar reconnects after a
+        // navigation. That is a re-assert, not the user opening the app, so it
+        // must not steal focus or expand a window they deliberately collapsed.
+        const opening = !restoringOpenState && !windows.visible;
+        windows.openAll(opening, true, opening);
+        windows.broadcastNotice('Click to select · Shift-click to add · drag to marquee');
+        requestInsertionZones();
+      } else {
+        overlay.disable();
+        windows.hideAll();
+      }
+      restoringOpenState = false;
+    });
+
+    server.on<ServerReadyMessage>(SERVER_EVENTS.ready, ({ protocolVersion, history, agent }) => {
+      if (disposed || protocolVersion !== PROTOCOL_VERSION) return;
+      windows.setProvider(agent);
+      windows.setHistory(history);
+      requestInsertionZones();
+      if (agent.provider !== 'none' && !agent.authenticated) {
+        windows.broadcastNotice(agent.message, true);
+      }
+    });
+    server.on<SelectionResolvedMessage>(SERVER_EVENTS.selection, ({ requestId, context }) => {
+      if (disposed || !pendingInspectRequests.delete(requestId)) return;
+      overlay.setSelection(context);
+      windows.broadcastNotice('Source-backed selection resolved locally.');
+    });
+    server.on<InsertionZonesResolvedMessage>(SERVER_EVENTS.insertionZones, ({ requestId, zones }) => {
+      if (disposed || requestId !== insertionZonesRequestId) return;
+      insertionZonesRequestId = undefined;
+      overlay.setInsertionZones(zones);
+    });
+    server.on<OperationCompletedMessage>(SERVER_EVENTS.operation, ({ transaction, history }) => {
+      if (disposed) return;
+      windows.setHistory(history);
+      windows.broadcastNotice(`${humanize(transaction.kind)} applied; Vite HMR is updating the page.`);
+      requestInsertionZones();
+      if (transaction.kind === 'reorder-sibling') overlay.clearSelection();
+    });
+    server.on<HistoryChangedMessage>(SERVER_EVENTS.history, (history) => {
+      if (!disposed) windows.setHistory(history);
+    });
+    server.on<VisualEditorErrorMessage>(SERVER_EVENTS.error, ({ requestId, message, fallbackEligible }) => {
+      if (disposed) return;
+      if (requestId !== undefined) {
+        const nodeId = pendingInspectRequests.get(requestId);
+        pendingInspectRequests.delete(requestId);
+        if (nodeId !== undefined) overlay.rejectSelection(nodeId);
+      }
+      windows.broadcastNotice(
+        fallbackEligible ? `${message} Ask AI or open the source to continue.` : message,
+        true,
+      );
+    });
+    server.on<AgentOperationEvent>(SERVER_EVENTS.agentEvent, (event) => {
+      if (disposed) return;
+      // Progress belongs to the window that started the run; a sibling window
+      // must not report a run it never made.
+      const drawer = windows.handleAgentEvent(event);
+      drawer?.setNotice(
+        event.state === 'completion'
+          ? event.transaction === undefined
+            ? 'AI response completed without changing source.'
+            : 'AI changes applied. Undo is available.'
+          : event.state === 'failure'
+            ? 'The AI run failed. Review the message for details.'
+            : `AI agent · ${humanize(event.state)}…`,
+        event.state === 'failure',
+      );
+    });
+
+    server.send<ClientReadyMessage>(CLIENT_EVENTS.ready, {
+      protocolVersion: PROTOCOL_VERSION,
+      route: window.location.pathname,
+      pendingAgentRequestIds: windows.pendingRequestIds(),
+      activeSessionIds: windows.sessionIds(),
+    });
+
+    if (readSession(APP_OPEN_KEY) === 'true') {
+      window.setTimeout(() => app.toggleState({ state: true }), 0);
+    }
+
+    // A client-side navigation swaps the document body and moves the toolbar
+    // into it. Every selection and node id then refers to a page that is gone,
+    // and the view transition can leave the chat windows hidden behind its
+    // snapshot, so the editor re-establishes itself against the new page.
+    const onNavigation = (): void => {
+      if (disposed) return;
+      ensureMounted();
+      overlay.clearSelection();
+      windows.handleNavigation();
+      if (windows.visible || readSession(APP_OPEN_KEY) === 'true') {
+        overlay.enable();
+        overlay.start();
+        windows.openAll(false, true, false);
+      }
+      requestInsertionZones();
+    };
+    document.addEventListener('astro:after-swap', onNavigation);
+    document.addEventListener('astro:page-load', onNavigation);
+    window.addEventListener('popstate', onNavigation);
+
+    const cleanup = (): void => {
+      if (disposed) return;
+      disposed = true;
+      document.removeEventListener('astro:after-swap', onNavigation);
+      document.removeEventListener('astro:page-load', onNavigation);
+      window.removeEventListener('popstate', onNavigation);
+      overlay.destroy();
+      diagnosticActions.destroy();
+      windows.destroy();
+    };
+    import.meta.hot?.dispose(cleanup);
+
+    function execute(command: DeterministicVisualCommand): void {
+      windows.broadcastNotice('Applying a deterministic source transformation…');
+      server.send(CLIENT_EVENTS.execute, {
+        requestId: createRequestId(),
+        command,
+      });
+    }
+
+    function requestInsertionZones(): void {
+      insertionZonesRequestId = createRequestId();
+      server.send(CLIENT_EVENTS.insertionZones, {
+        requestId: insertionZonesRequestId,
+        route: window.location.pathname,
+      });
+    }
+  },
+});
+
+function createRequestId(): string {
+  return crypto.randomUUID();
+}
+
+function humanize(kind: string): string {
+  return kind.replaceAll('-', ' ');
+}
+
+function readSession(key: string): string | null {
+  try {
+    return sessionStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function writeSession(key: string, value: string): void {
+  try {
+    sessionStorage.setItem(key, value);
+  } catch {
+    // The editor remains usable if session storage is restricted.
+  }
+}