doe-sdk 0.1.0

package/templates/extension/src/components/steps/ConfigStep.tsx

@@ -0,0 +1,63 @@
+/**
+ * ConfigStep - Onboarding step demonstrating Config API
+ *
+ * Uses shared ConfigControls component for DRY code.
+ */
+import React, { useState } from "react";
+import type { DOEExtensionAPI } from "doe-sdk/runtime";
+import { StepContainer } from "../StepContainer";
+import { STEP_INFO } from "../../hooks/useOnboarding";
+import { ConfigControls } from "../shared";
+
+export interface ConfigStepProps {
+  api: DOEExtensionAPI;
+  stepNumber: number;
+  totalSteps: number;
+  onPrev: () => void;
+  onNext: () => void;
+  isLastStep?: boolean;
+}
+
+export function ConfigStep({
+  api,
+  stepNumber,
+  totalSteps,
+  onPrev,
+  onNext,
+  isLastStep,
+}: ConfigStepProps): React.ReactElement {
+  const [result, setResult] = useState<string>("");
+
+  const { title, description, icon } = STEP_INFO.config;
+
+  const codeExample = `// Get a config value
+const city = await api.config.get<string>("defaultCity");
+
+// Set a config value
+await api.config.set("defaultCity", "Tokyo");
+
+// Open settings UI
+await api.config.openSettings();
+
+// Listen for config changes
+api.events.onConfigChange(({ key, value }) => {
+  console.log(\`Config \${key} changed to \${value}\`);
+});`;
+
+  return (
+    <StepContainer
+      title={title}
+      description={description}
+      icon={icon}
+      stepNumber={stepNumber}
+      totalSteps={totalSteps}
+      onPrev={onPrev}
+      onNext={onNext}
+      isLastStep={isLastStep}
+      codeExample={codeExample}
+      result={result}
+    >
+      <ConfigControls api={api} onResult={setResult} />
+    </StepContainer>
+  );
+}

package/templates/extension/src/components/steps/EventsStep.tsx

@@ -0,0 +1,69 @@
+/**
+ * EventsStep - Onboarding step demonstrating Events API
+ *
+ * Uses shared EventsControls component for DRY code.
+ */
+import React, { useState } from "react";
+import type { DOEExtensionAPI } from "doe-sdk/runtime";
+import { StepContainer } from "../StepContainer";
+import { STEP_INFO } from "../../hooks/useOnboarding";
+import { EventsControls } from "../shared";
+
+export interface EventsStepProps {
+  api: DOEExtensionAPI;
+  stepNumber: number;
+  totalSteps: number;
+  onPrev: () => void;
+  onNext: () => void;
+  isLastStep?: boolean;
+}
+
+export function EventsStep({
+  api,
+  stepNumber,
+  totalSteps,
+  onPrev,
+  onNext,
+  isLastStep,
+}: EventsStepProps): React.ReactElement {
+  const [result, setResult] = useState<string>("Listening for events...");
+
+  const { title, description, icon } = STEP_INFO.events;
+
+  const codeExample = `// Selection changes
+const unsub1 = api.events.onSelectionChange((payload) => {
+  console.log("Selected shapes:", payload.shapeIds);
+});
+
+// Canvas changes (create, update, delete)
+const unsub2 = api.events.onCanvasChange((payload) => {
+  console.log(\`\${payload.type}: \${payload.shapeIds.length} shapes\`);
+});
+
+// Theme changes
+const unsub3 = api.events.onThemeChange((payload) => {
+  console.log("Theme changed to:", payload.mode);
+});
+
+// Clean up when done
+unsub1();
+unsub2();
+unsub3();`;
+
+  return (
+    <StepContainer
+      title={title}
+      description={description}
+      icon={icon}
+      stepNumber={stepNumber}
+      totalSteps={totalSteps}
+      onPrev={onPrev}
+      onNext={onNext}
+      isLastStep={isLastStep}
+      codeExample={codeExample}
+      result={result}
+    >
+      <EventsControls api={api} onResult={setResult} />
+    </StepContainer>
+  );
+}

package/templates/extension/src/components/steps/InfoStep.tsx

@@ -0,0 +1,70 @@
+/**
+ * InfoStep - Onboarding step demonstrating Workspace + Theme APIs
+ *
+ * Uses shared InfoControls component for DRY code.
+ */
+import React, { useState } from "react";
+import type { DOEExtensionAPI } from "doe-sdk/runtime";
+import { StepContainer } from "../StepContainer";
+import { STEP_INFO } from "../../hooks/useOnboarding";
+import { InfoControls } from "../shared";
+
+export interface InfoStepProps {
+  api: DOEExtensionAPI;
+  stepNumber: number;
+  totalSteps: number;
+  onPrev: () => void;
+  onNext: () => void;
+  isLastStep?: boolean;
+}
+
+export function InfoStep({
+  api,
+  stepNumber,
+  totalSteps,
+  onPrev,
+  onNext,
+  isLastStep,
+}: InfoStepProps): React.ReactElement {
+  const [result, setResult] = useState<string>("");
+
+  const { title, description, icon } = STEP_INFO.info;
+
+  const codeExample = `// Get workspace information
+const workspace = await api.workspace.getInfo();
+console.log("Workspace:", workspace.name);
+
+// Get current user
+const user = await api.workspace.getCurrentUser();
+if (user) {
+  console.log("User:", user.displayName);
+  console.log("Avatar:", user.avatarUrl);
+}
+
+// Get current theme
+const theme = await api.ui.getTheme();
+console.log("Theme mode:", theme.mode);
+console.log("Colors:", theme.colors);
+
+// Listen for theme changes
+api.events.onThemeChange((payload) => {
+  console.log("Theme changed to:", payload.mode);
+});`;
+
+  return (
+    <StepContainer
+      title={title}
+      description={description}
+      icon={icon}
+      stepNumber={stepNumber}
+      totalSteps={totalSteps}
+      onPrev={onPrev}
+      onNext={onNext}
+      isLastStep={isLastStep}
+      codeExample={codeExample}
+      result={result}
+    >
+      <InfoControls api={api} onResult={setResult} />
+    </StepContainer>
+  );
+}

package/templates/extension/src/components/steps/NetworkStep.tsx

@@ -0,0 +1,70 @@
+/**
+ * NetworkStep - Onboarding step demonstrating Network API
+ *
+ * Uses shared NetworkControls component for DRY code.
+ */
+import React, { useState } from "react";
+import type { DOEExtensionAPI } from "doe-sdk/runtime";
+import { StepContainer } from "../StepContainer";
+import { STEP_INFO } from "../../hooks/useOnboarding";
+import { NetworkControls } from "../shared";
+
+export interface NetworkStepProps {
+  api: DOEExtensionAPI;
+  stepNumber: number;
+  totalSteps: number;
+  onPrev: () => void;
+  onNext: () => void;
+  isLastStep?: boolean;
+}
+
+export function NetworkStep({
+  api,
+  stepNumber,
+  totalSteps,
+  onPrev,
+  onNext,
+  isLastStep,
+}: NetworkStepProps): React.ReactElement {
+  const [result, setResult] = useState<string>("");
+
+  const { title, description, icon } = STEP_INFO.network;
+
+  const codeExample = `// Call any external API from your extension
+// (add domains to hostPermissions in manifest.json)
+
+// Example: Fetch from GitHub API
+const response = await api.network.fetch(
+  "https://api.github.com/users/torvalds",
+  { timeout: 10000 }
+);
+
+if (response.ok) {
+  const user = await response.json();
+  console.log("Profile:", user.name);
+  console.log("Repos:", user.public_repos);
+}
+
+// Example: Fetch from any REST API
+const jokes = await api.network.fetch(
+  "https://icanhazdadjoke.com/",
+  { headers: { Accept: "application/json" } }
+);`;
+
+  return (
+    <StepContainer
+      title={title}
+      description={description}
+      icon={icon}
+      stepNumber={stepNumber}
+      totalSteps={totalSteps}
+      onPrev={onPrev}
+      onNext={onNext}
+      isLastStep={isLastStep}
+      codeExample={codeExample}
+      result={result}
+    >
+      <NetworkControls api={api} onResult={setResult} />
+    </StepContainer>
+  );
+}

package/templates/extension/src/components/steps/StorageStep.tsx

@@ -0,0 +1,61 @@
+/**
+ * StorageStep - Onboarding step demonstrating Storage API
+ *
+ * Uses shared StorageControls component for DRY code.
+ */
+import React, { useState } from "react";
+import type { DOEExtensionAPI } from "doe-sdk/runtime";
+import { StepContainer } from "../StepContainer";
+import { STEP_INFO } from "../../hooks/useOnboarding";
+import { StorageControls } from "../shared";
+
+export interface StorageStepProps {
+  api: DOEExtensionAPI;
+  stepNumber: number;
+  totalSteps: number;
+  onPrev: () => void;
+  onNext: () => void;
+  isLastStep?: boolean;
+}
+
+export function StorageStep({
+  api,
+  stepNumber,
+  totalSteps,
+  onPrev,
+  onNext,
+  isLastStep,
+}: StorageStepProps): React.ReactElement {
+  const [result, setResult] = useState<string>("");
+
+  const { title, description, icon } = STEP_INFO.storage;
+
+  const codeExample = `// Save a value
+await api.storage.set("myKey", "myValue");
+
+// Load a value
+const value = await api.storage.get<string>("myKey");
+
+// Delete a value
+await api.storage.delete("myKey");
+
+// List all keys
+const keys = await api.storage.keys();`;
+
+  return (
+    <StepContainer
+      title={title}
+      description={description}
+      icon={icon}
+      stepNumber={stepNumber}
+      totalSteps={totalSteps}
+      onPrev={onPrev}
+      onNext={onNext}
+      isLastStep={isLastStep}
+      codeExample={codeExample}
+      result={result}
+    >
+      <StorageControls api={api} onResult={setResult} />
+    </StepContainer>
+  );
+}

package/templates/extension/src/components/steps/UIStep.tsx

@@ -0,0 +1,70 @@
+/**
+ * UIStep - Onboarding step demonstrating UI API
+ *
+ * Uses shared UIControls component for DRY code.
+ */
+import React, { useState } from "react";
+import type { DOEExtensionAPI } from "doe-sdk/runtime";
+import { StepContainer } from "../StepContainer";
+import { STEP_INFO } from "../../hooks/useOnboarding";
+import { UIControls } from "../shared";
+
+export interface UIStepProps {
+  api: DOEExtensionAPI;
+  stepNumber: number;
+  totalSteps: number;
+  onPrev: () => void;
+  onNext: () => void;
+  isLastStep?: boolean;
+}
+
+export function UIStep({
+  api,
+  stepNumber,
+  totalSteps,
+  onPrev,
+  onNext,
+  isLastStep,
+}: UIStepProps): React.ReactElement {
+  const [result, setResult] = useState<string>("");
+
+  const { title, description, icon } = STEP_INFO.ui;
+
+  const codeExample = `// Show right-side panel
+await api.ui.showPanel({ title: "My Panel", width: 400 });
+await api.ui.hidePanel();
+
+// Show centered modal dialog
+await api.ui.showModal({ title: "My Modal", width: 500, height: 400 });
+await api.ui.hideModal();
+
+// Show toast notifications
+await api.ui.showToast("Operation complete!", {
+  type: "success",  // "info" | "success" | "warning" | "error"
+  duration: 3000,   // milliseconds
+});
+
+// Show confirmation dialog
+const confirmed = await api.ui.confirm("Delete this item?", {
+  title: "Confirm Delete",
+  confirmText: "Delete",
+  cancelText: "Keep",
+});`;
+
+  return (
+    <StepContainer
+      title={title}
+      description={description}
+      icon={icon}
+      stepNumber={stepNumber}
+      totalSteps={totalSteps}
+      onPrev={onPrev}
+      onNext={onNext}
+      isLastStep={isLastStep}
+      codeExample={codeExample}
+      result={result}
+    >
+      <UIControls api={api} onResult={setResult} />
+    </StepContainer>
+  );
+}

package/templates/extension/src/hooks/useDoe.ts

@@ -0,0 +1,93 @@
+/**
+ * useDoe - React Hook for DOE Extension API
+ *
+ * Wraps the official SDK runtime initializer and provides
+ * React-friendly state (`isReady`, `error`) for extension apps.
+ */
+import { useState, useEffect, useSyncExternalStore } from "react";
+import {
+  initializeExtension,
+  type DOEExtensionAPI,
+} from "doe-sdk/runtime";
+
+// ============================================================================
+// REACT INTEGRATION
+// ============================================================================
+
+let globalApi: DOEExtensionAPI | null = null;
+let apiInitPromise: Promise<DOEExtensionAPI> | null = null;
+let initError: Error | null = null;
+const subscribers = new Set<() => void>();
+
+// Cached snapshot for useSyncExternalStore (must be referentially stable)
+let cachedSnapshot: { api: DOEExtensionAPI | null; error: Error | null } = { api: null, error: null };
+
+function updateSnapshot(): void {
+  cachedSnapshot = { api: globalApi, error: initError };
+}
+
+function notifySubscribers(): void {
+  updateSnapshot();
+  for (const sub of subscribers) sub();
+}
+
+async function initializeApi(): Promise<DOEExtensionAPI> {
+  if (globalApi) return globalApi;
+  if (apiInitPromise) return apiInitPromise;
+
+  apiInitPromise = initializeExtension()
+    .then((api) => {
+      globalApi = api;
+      notifySubscribers();
+      return api;
+    })
+    .catch((error) => {
+      initError = error instanceof Error ? error : new Error(String(error));
+      notifySubscribers();
+      throw initError;
+    });
+
+  return apiInitPromise;
+}
+
+function getApiSnapshot() {
+  return cachedSnapshot;
+}
+
+function subscribeToApi(callback: () => void): () => void {
+  subscribers.add(callback);
+  return () => subscribers.delete(callback);
+}
+
+// ============================================================================
+// HOOK
+// ============================================================================
+
+export interface UseDoeResult {
+  api: DOEExtensionAPI | null;
+  isReady: boolean;
+  error: Error | null;
+}
+
+export function useDoe(): UseDoeResult {
+  const [isInitializing, setIsInitializing] = useState(!globalApi);
+
+  const { api, error } = useSyncExternalStore(
+    subscribeToApi,
+    getApiSnapshot,
+    getApiSnapshot
+  );
+
+  useEffect(() => {
+    if (!globalApi && !apiInitPromise) {
+      setIsInitializing(true);
+      initializeApi().finally(() => setIsInitializing(false));
+    }
+  }, []);
+
+  return {
+    api,
+    isReady: api !== null && !isInitializing,
+    error,
+  };
+}