@jxrstudios/jxr 1.0.10 → 1.1.11

package/zzz_react_template/contexts/JXRContext.tsx

@@ -0,0 +1,264 @@
+/**
+ * JXR.js — React Context & Runtime Hooks
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Design: LavaFlow OS — Thermal Precision + Edge Command
+ * Layer: UI / State Management
+ *
+ * Provides reactive access to all JXR runtime subsystems via React context.
+ * All state updates are batched and debounced to prevent render thrashing.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  useCallback,
+  useRef,
+  type ReactNode,
+} from 'react';
+import {
+  jxrRuntime,
+  type JXRRuntimeMetrics,
+  type VirtualFile,
+  type VirtualDirectory,
+} from '@/lib/jxr-runtime';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type EditorTab = {
+  path: string;
+  dirty: boolean;
+};
+
+export type PreviewState = 'idle' | 'building' | 'ready' | 'error';
+
+export interface JXRContextValue {
+  // Runtime
+  runtime: typeof jxrRuntime;
+  metrics: JXRRuntimeMetrics | null;
+  isInitialized: boolean;
+
+  // File system
+  fileTree: VirtualDirectory | null;
+  openFile: (path: string) => void;
+  closeFile: (path: string) => void;
+  saveFile: (path: string, content: string) => void;
+  createFile: (path: string, content?: string) => void;
+  deleteFile: (path: string) => void;
+  activeFile: VirtualFile | null;
+  openTabs: EditorTab[];
+
+  // Preview
+  previewState: PreviewState;
+  previewHtml: string;
+  previewError: string | null;
+  refreshPreview: () => void;
+
+  // Terminal
+  terminalLines: TerminalLine[];
+  pushTerminalLine: (line: TerminalLine) => void;
+  clearTerminal: () => void;
+}
+
+export interface TerminalLine {
+  id: string;
+  type: 'info' | 'success' | 'error' | 'warn' | 'command' | 'output';
+  text: string;
+  timestamp: number;
+}
+
+// ─── Context ──────────────────────────────────────────────────────────────────
+
+const JXRContext = createContext<JXRContextValue | null>(null);
+
+export function useJXR(): JXRContextValue {
+  const ctx = useContext(JXRContext);
+  if (!ctx) throw new Error('useJXR must be used within JXRProvider');
+  return ctx;
+}
+
+// ─── Provider ─────────────────────────────────────────────────────────────────
+
+export function JXRProvider({ children }: { children: ReactNode }) {
+  const [isInitialized, setIsInitialized] = useState(false);
+  const [metrics, setMetrics] = useState<JXRRuntimeMetrics | null>(null);
+  const [fileTree, setFileTree] = useState<VirtualDirectory | null>(null);
+  const [activeFilePath, setActiveFilePath] = useState<string | null>('/src/App.tsx');
+  const [openTabs, setOpenTabs] = useState<EditorTab[]>([
+    { path: '/src/App.tsx', dirty: false },
+    { path: '/src/components/Button.tsx', dirty: false },
+    { path: '/src/hooks/useCounter.ts', dirty: false },
+  ]);
+  const [previewState, setPreviewState] = useState<PreviewState>('idle');
+  const [previewHtml, setPreviewHtml] = useState('');
+  const [previewError, setPreviewError] = useState<string | null>(null);
+  const [terminalLines, setTerminalLines] = useState<TerminalLine[]>([]);
+  const previewDebounce = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const lineCounter = useRef(0);
+
+  // ─── Initialize runtime ───────────────────────────────────────────────────
+
+  useEffect(() => {
+    let unsubMetrics: (() => void) | null = null;
+    let unsubFS: (() => void) | null = null;
+
+    const init = async () => {
+      pushLine('command', '$ jxr init --edge --moq --crypto');
+      pushLine('info', 'Initializing JXR.js Edge Runtime v1.0.0...');
+
+      await jxrRuntime.init();
+
+      pushLine('success', '✓ MoQ transport connected (edge://jxr-local)');
+      pushLine('success', '✓ Worker pool initialized (cores: ' + (navigator.hardwareConcurrency ?? 4) + ')');
+      pushLine('success', '✓ Web Crypto engine ready (AES-GCM-256 + ECDSA P-256)');
+      pushLine('success', '✓ Virtual FS mounted (/src)');
+      pushLine('success', '✓ Module resolver online (esm.sh CDN)');
+      pushLine('output', '');
+      pushLine('output', 'JXR.js ready. No build step required.');
+
+      // Subscribe to metrics
+      unsubMetrics = jxrRuntime.onMetrics((m) => setMetrics(m));
+
+      // Subscribe to FS changes
+      unsubFS = jxrRuntime.vfs.onChange(() => {
+        setFileTree(jxrRuntime.vfs.buildTree('/'));
+        schedulePreviewRefresh();
+      });
+
+      setFileTree(jxrRuntime.vfs.buildTree('/'));
+      setIsInitialized(true);
+      schedulePreviewRefresh();
+    };
+
+    init().catch((err) => {
+      pushLine('error', `✗ Runtime init failed: ${err.message}`);
+    });
+
+    return () => {
+      unsubMetrics?.();
+      unsubFS?.();
+      jxrRuntime.dispose();
+    };
+  }, []);
+
+  // ─── Terminal helpers ─────────────────────────────────────────────────────
+
+  const pushLine = useCallback((type: TerminalLine['type'], text: string) => {
+    setTerminalLines((prev) => [
+      ...prev.slice(-200), // Keep last 200 lines
+      { id: `line-${++lineCounter.current}`, type, text, timestamp: Date.now() },
+    ]);
+  }, []);
+
+  const pushTerminalLine = useCallback(
+    (line: TerminalLine) => setTerminalLines((prev) => [...prev.slice(-200), line]),
+    []
+  );
+
+  const clearTerminal = useCallback(() => setTerminalLines([]), []);
+
+  // ─── Preview engine ───────────────────────────────────────────────────────
+
+  const schedulePreviewRefresh = useCallback(() => {
+    if (previewDebounce.current) clearTimeout(previewDebounce.current);
+    previewDebounce.current = setTimeout(() => {
+      refreshPreview();
+    }, 300);
+  }, []);
+
+  const refreshPreview = useCallback(() => {
+    setPreviewState('building');
+    setPreviewError(null);
+
+    try {
+      const html = jxrRuntime.buildPreviewDocument();
+      setPreviewHtml(html);
+      setPreviewState('ready');
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      setPreviewError(message);
+      setPreviewState('error');
+      pushLine('error', `Preview error: ${message}`);
+    }
+  }, [pushLine]);
+
+  // ─── File operations ──────────────────────────────────────────────────────
+
+  const openFile = useCallback((path: string) => {
+    setActiveFilePath(path);
+    setOpenTabs((prev) => {
+      if (prev.find((t) => t.path === path)) return prev;
+      return [...prev, { path, dirty: false }];
+    });
+  }, []);
+
+  const closeFile = useCallback(
+    (path: string) => {
+      setOpenTabs((prev) => {
+        const next = prev.filter((t) => t.path !== path);
+        if (activeFilePath === path && next.length > 0) {
+          setActiveFilePath(next[next.length - 1].path);
+        }
+        return next;
+      });
+    },
+    [activeFilePath]
+  );
+
+  const saveFile = useCallback(
+    (path: string, content: string) => {
+      jxrRuntime.vfs.write(path, content);
+      jxrRuntime.cache.invalidate(path);
+      setOpenTabs((prev) =>
+        prev.map((t) => (t.path === path ? { ...t, dirty: false } : t))
+      );
+      pushLine('success', `✓ Saved ${path}`);
+    },
+    [pushLine]
+  );
+
+  const createFile = useCallback(
+    (path: string, content = '') => {
+      jxrRuntime.vfs.write(path, content);
+      openFile(path);
+      pushLine('success', `✓ Created ${path}`);
+    },
+    [openFile, pushLine]
+  );
+
+  const deleteFile = useCallback(
+    (path: string) => {
+      jxrRuntime.vfs.delete(path);
+      closeFile(path);
+      pushLine('warn', `⚠ Deleted ${path}`);
+    },
+    [closeFile, pushLine]
+  );
+
+  const activeFile = activeFilePath ? jxrRuntime.vfs.read(activeFilePath) : null;
+
+  const value: JXRContextValue = {
+    runtime: jxrRuntime,
+    metrics,
+    isInitialized,
+    fileTree,
+    openFile,
+    closeFile,
+    saveFile,
+    createFile,
+    deleteFile,
+    activeFile,
+    openTabs,
+    previewState,
+    previewHtml,
+    previewError,
+    refreshPreview,
+    terminalLines,
+    pushTerminalLine,
+    clearTerminal,
+  };
+
+  return <JXRContext.Provider value={value}>{children}</JXRContext.Provider>;
+}

package/zzz_react_template/contexts/ThemeContext.tsx

@@ -0,0 +1,64 @@
+import React, { createContext, useContext, useEffect, useState } from "react";
+
+type Theme = "light" | "dark";
+
+interface ThemeContextType {
+  theme: Theme;
+  toggleTheme: () => void;
+  switchable: boolean;
+}
+
+const ThemeContext = createContext<ThemeContextType | undefined>(undefined);
+
+interface ThemeProviderProps {
+  children: React.ReactNode;
+  defaultTheme?: Theme;
+  switchable?: boolean;
+}
+
+export function ThemeProvider({
+  children,
+  defaultTheme = "light",
+  switchable = false,
+}: ThemeProviderProps) {
+  const [theme, setTheme] = useState<Theme>(() => {
+    if (switchable) {
+      const stored = localStorage.getItem("theme");
+      return (stored as Theme) || defaultTheme;
+    }
+    return defaultTheme;
+  });
+
+  useEffect(() => {
+    const root = document.documentElement;
+    if (theme === "dark") {
+      root.classList.add("dark");
+    } else {
+      root.classList.remove("dark");
+    }
+
+    if (switchable) {
+      localStorage.setItem("theme", theme);
+    }
+  }, [theme, switchable]);
+
+  const toggleTheme = () => {
+    if (switchable) {
+      setTheme(prev => (prev === "light" ? "dark" : "light"));
+    }
+  };
+
+  return (
+    <ThemeContext.Provider value={{ theme, toggleTheme, switchable }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error("useTheme must be used within ThemeProvider");
+  }
+  return context;
+}

package/zzz_react_template/hooks/useComposition.ts

@@ -0,0 +1,81 @@
+import { useRef } from "react";
+import { usePersistFn } from "./usePersistFn";
+
+export interface UseCompositionReturn<
+  T extends HTMLInputElement | HTMLTextAreaElement,
+> {
+  onCompositionStart: React.CompositionEventHandler<T>;
+  onCompositionEnd: React.CompositionEventHandler<T>;
+  onKeyDown: React.KeyboardEventHandler<T>;
+  isComposing: () => boolean;
+}
+
+export interface UseCompositionOptions<
+  T extends HTMLInputElement | HTMLTextAreaElement,
+> {
+  onKeyDown?: React.KeyboardEventHandler<T>;
+  onCompositionStart?: React.CompositionEventHandler<T>;
+  onCompositionEnd?: React.CompositionEventHandler<T>;
+}
+
+type TimerResponse = ReturnType<typeof setTimeout>;
+
+export function useComposition<
+  T extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
+>(options: UseCompositionOptions<T> = {}): UseCompositionReturn<T> {
+  const {
+    onKeyDown: originalOnKeyDown,
+    onCompositionStart: originalOnCompositionStart,
+    onCompositionEnd: originalOnCompositionEnd,
+  } = options;
+
+  const c = useRef(false);
+  const timer = useRef<TimerResponse | null>(null);
+  const timer2 = useRef<TimerResponse | null>(null);
+
+  const onCompositionStart = usePersistFn((e: React.CompositionEvent<T>) => {
+    if (timer.current) {
+      clearTimeout(timer.current);
+      timer.current = null;
+    }
+    if (timer2.current) {
+      clearTimeout(timer2.current);
+      timer2.current = null;
+    }
+    c.current = true;
+    originalOnCompositionStart?.(e);
+  });
+
+  const onCompositionEnd = usePersistFn((e: React.CompositionEvent<T>) => {
+    // 使用两层 setTimeout 来处理 Safari 浏览器中 compositionEnd 先于 onKeyDown 触发的问题
+    timer.current = setTimeout(() => {
+      timer2.current = setTimeout(() => {
+        c.current = false;
+      });
+    });
+    originalOnCompositionEnd?.(e);
+  });
+
+  const onKeyDown = usePersistFn((e: React.KeyboardEvent<T>) => {
+    // 在 composition 状态下，阻止 ESC 和 Enter（非 shift+Enter）事件的冒泡
+    if (
+      c.current &&
+      (e.key === "Escape" || (e.key === "Enter" && !e.shiftKey))
+    ) {
+      e.stopPropagation();
+      return;
+    }
+    originalOnKeyDown?.(e);
+  });
+
+  const isComposing = usePersistFn(() => {
+    return c.current;
+  });
+
+  return {
+    onCompositionStart,
+    onCompositionEnd,
+    onKeyDown,
+    isComposing,
+  };
+}

package/zzz_react_template/hooks/useMobile.tsx

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+const MOBILE_BREAKPOINT = 768;
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(
+    undefined
+  );
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    };
+    mql.addEventListener("change", onChange);
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    return () => mql.removeEventListener("change", onChange);
+  }, []);
+
+  return !!isMobile;
+}

package/zzz_react_template/hooks/usePersistFn.ts

@@ -0,0 +1,20 @@
+import { useRef } from "react";
+
+type noop = (...args: any[]) => any;
+
+/**
+ * usePersistFn instead of useCallback to reduce cognitive load
+ */
+export function usePersistFn<T extends noop>(fn: T) {
+  const fnRef = useRef<T>(fn);
+  fnRef.current = fn;
+
+  const persistFn = useRef<T>(null);
+  if (!persistFn.current) {
+    persistFn.current = function (this: unknown, ...args) {
+      return fnRef.current!.apply(this, args);
+    } as T;
+  }
+
+  return persistFn.current!;
+}