@sutrata/editor 0.1.0

package/src/extensions/storage-adapter.ts

@@ -0,0 +1,65 @@
+import { createContext, useContext } from 'react'
+import type { VersionEntry } from '../types'
+import type { ScreenplayStyleDefinition } from '../styles/types'
+
+/**
+ * Injected by the embedder (OSS spec §11.5). The OSS app supplies a local
+ * implementation (IndexedDB + File System Access API, see @sutrata/app's
+ * local-storage-adapter.ts); Sutrata Cloud supplies a networked one.
+ *
+ * `handle` fields are opaque (`unknown`) on purpose: a web FileSystemFileHandle
+ * has no equivalent in a non-web adapter. Callers just thread whatever the
+ * adapter returned back into a later saveFile() call without inspecting it.
+ */
+export interface StorageAdapter {
+  saveDocument(path: string, content: string): Promise<void>
+  loadDocument(path: string): Promise<string | null>
+  listVersions(path: string): Promise<VersionEntry[]>
+
+  openFile(): Promise<{ name: string; content: string; handle: unknown } | null>
+  openDocx(): Promise<{ name: string; buffer: ArrayBuffer } | null>
+  openStyleJson(): Promise<{ name: string; text: string } | null>
+  saveFile(
+    name: string,
+    content: string,
+    existingHandle?: unknown,
+  ): Promise<{ savedName: string; handle: unknown } | null>
+
+  saveStyle(style: ScreenplayStyleDefinition): Promise<void>
+  loadAllStyles(): Promise<ScreenplayStyleDefinition[]>
+  deleteStyle(id: string): Promise<void>
+
+  /**
+   * Optional: lets a restored session (see DocumentContext's boot-recovery
+   * effect) keep writing straight back to the file the user had open instead
+   * of forcing Save As. Adapters without a handle concept (Cloud, or a
+   * browser build with no persisted-handle support) simply omit these; the
+   * caller feature-detects with `?.`. `restoreFileHandle` should only ever
+   * return a handle that's usable without prompting — if permission would
+   * need to be re-requested, return null and let the user Save As instead.
+   */
+  persistFileHandle?(path: string, handle: unknown): Promise<void>
+  restoreFileHandle?(path: string): Promise<unknown | null>
+
+  /**
+   * Optional: delete all saved versions of a document. Used by the version
+   * history UI's "clear all versions" action.
+   */
+  deleteAllVersions?(path: string): Promise<void>
+
+  /**
+   * Optional: save a version snapshot for a document. Adapters should only
+   * persist a new version entry when there is a difference against the previous version.
+   */
+  saveVersion?(path: string, content: string): Promise<boolean>
+}
+
+const StorageAdapterContext = createContext<StorageAdapter | null>(null)
+
+export const StorageAdapterProvider = StorageAdapterContext.Provider
+
+export function useStorageAdapter(): StorageAdapter {
+  const adapter = useContext(StorageAdapterContext)
+  if (!adapter) throw new Error('useStorageAdapter must be used inside a StorageAdapterProvider (DocumentProvider supplies one)')
+  return adapter
+}

package/src/extensions/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Type-only extension-point surface (OSS spec §11.5). These declare the shape
+ * embedders (Sutrata Cloud, third-party plugins) will implement, but nothing
+ * in @sutrata/editor is wired to them yet — ai-client.ts and voice-service.ts
+ * are still direct imports within this package, not injected. Promoting them
+ * to real dependency-injected providers (matching StorageAdapter's pattern in
+ * ./storage-adapter.ts) is future work; see docs/TODO.
+ *
+ * [P1 interface, stable by P2] per the OSS spec — these shapes may still
+ * change before they're load-bearing.
+ */
+
+/** LLM completion with streaming; declares capabilities and data-policy text for disclosure. */
+export interface AIProvider {
+  id: string
+  displayName: string
+  dataPolicyText: string
+  complete(prompt: string, opts?: { stream?: boolean }): Promise<string>
+}
+
+/** Speech-to-text. */
+export interface SpeechProvider {
+  id: string
+  displayName: string
+  transcribe(audio: Blob, opts?: { language?: string }): Promise<string>
+}
+
+/** Current user identity, permissions (read-only, comment, edit), feature flags. */
+export interface SessionContext {
+  userId: string | null
+  displayName: string | null
+  permission: 'read' | 'comment' | 'edit'
+  featureFlags: Record<string, boolean>
+}
+
+/** Add side panels, inspector sections, and app-bar items; receives the AST and scene IDs. */
+export interface PanelRegistry {
+  registerPanel(panel: { id: string; title: string; render: () => unknown }): void
+}
+
+/** Add commands, menu items, keyboard shortcuts. */
+export interface CommandRegistry {
+  registerCommand(command: { id: string; label: string; run: () => void; shortcut?: string }): void
+}
+
+/** Add export formats and report types. */
+export interface ExportRegistry {
+  registerExporter(exporter: { id: string; label: string; run: (text: string) => Promise<Blob> }): void
+}
+
+/** Hook to bind the editor state to an external real-time sync provider (e.g. a Yjs document). */
+export interface CollabBinding {
+  bind(): () => void
+}
+
+/** Render external annotations (comments, breakdown highlights, revision marks) anchored to
+ *  scene IDs and text ranges. */
+export interface DecorationProvider {
+  getDecorations(sceneId: string): Array<{ from: number; to: number; className: string }>
+}