@mathvoice/react 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# @mathvoice/react
+
+Voice-driven LaTeX editing as a controlled React component.
+
+## Installation
+
+```bash
+npm install @mathvoice/react
+```
+
+Also import the KaTeX stylesheet in your app entry point:
+
+```ts
+import 'katex/dist/katex.min.css';
+```
+
+## Usage
+
+```tsx
+import { StudioEditor } from '@mathvoice/react';
+
+export default function App() {
+  return (
+    <StudioEditor
+      initialLatex="\frac{-b \pm \sqrt{b^2-4ac}}{2a}"
+      apiEndpoint="/api/intent"
+      onMutation={(result) => console.log('updated:', result.after)}
+    />
+  );
+}
+```
+
+## Controlled mode
+
+```tsx
+const [latex, setLatex] = useState('\\frac{x}{2}');
+
+<StudioEditor
+  latex={latex}
+  onMutation={(result) => setLatex(result.after)}
+  editMode="ALGEBRA"
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `initialLatex` | `string` | `\\frac{-b}{2a}` | Starting LaTeX (uncontrolled) |
+| `latex` | `string` | — | Controlled LaTeX value |
+| `onMutation` | `(result: MutationResult) => void` | — | Called after every successful edit |
+| `editMode` | `'CORRECT' \| 'ALGEBRA' \| 'ASK'` | `'CORRECT'` | Enforced edit mode |
+| `voiceEnabled` | `boolean` | `true` | Show mic button placeholder |
+| `onModeChange` | `(mode: EditMode) => void` | — | Called when user switches mode |
+| `apiEndpoint` | `string` | `'/api/intent'` | Override the intent API URL |
+| `className` | `string` | — | CSS class on root element |
+| `style` | `React.CSSProperties` | — | Inline styles on root element |
+
+## API endpoint
+
+The component posts to `apiEndpoint` with:
+
+```json
+{
+  "rawText": "change the numerator to x squared",
+  "normalizedText": "change numerator to x squared",
+  "formulaContext": { "latex": "\\frac{-b}{2a}" },
+  "editMode": "CORRECT"
+}
+```
+
+Expected response: an `Intent` object (see `@mathvoice/react` types).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,80 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface Intent {
+    type: IntentType;
+    target?: {
+        role: string;
+    };
+    source?: {
+        role: string;
+    };
+    value?: {
+        raw: string;
+    };
+    term?: {
+        raw: string;
+    };
+    wrapper?: 'SQRT' | 'FRACTION';
+    operation?: 'ADD' | 'SUBTRACT' | 'MULTIPLY' | 'DIVIDE';
+    reason?: string;
+    confidence?: number;
+    source_tier?: string;
+    source_origin?: string;
+}
+type IntentType = 'REPLACE_VALUE' | 'DELETE_NODE' | 'INSERT_NODE' | 'REPARENT_NODE' | 'NEGATE_NODE' | 'WRAP_NODE' | 'APPLY_INVERSE' | 'TRANSPOSE_TERM' | 'UNKNOWN';
+
+type EditMode = 'CORRECT' | 'ALGEBRA' | 'ASK';
+interface DiffEntry {
+    op: string;
+    role?: string;
+    before?: string;
+    after?: string;
+    srcRole?: string;
+    tgtRole?: string;
+    srcVal?: string;
+    tgtVal?: string;
+    wrapper?: string;
+    operation?: string;
+    value?: string;
+    lhsBefore?: string;
+    lhsAfter?: string;
+    rhsBefore?: string;
+    rhsAfter?: string;
+    term?: string;
+    from?: string;
+    to?: string;
+    note?: string;
+}
+interface MutationResult {
+    success: boolean;
+    before: string;
+    after: string;
+    diff: DiffEntry | null;
+    error?: string;
+}
+
+interface StudioEditorProps {
+    /** Starting LaTeX string (uncontrolled). Defaults to \\frac{-b}{2a}. */
+    initialLatex?: string;
+    /** Fully-controlled LaTeX. When provided, the component renders this value
+     *  and calls onMutation on every successful edit but does not manage its
+     *  own undo stack. */
+    latex?: string;
+    /** Called after every successful mutation. */
+    onMutation?: (result: MutationResult) => void;
+    /** Edit mode to enforce. Defaults to 'CORRECT'. */
+    editMode?: EditMode;
+    /** Show / hide the microphone button. Defaults to true. */
+    voiceEnabled?: boolean;
+    /** Called when the user changes modes (only when editMode is unset). */
+    onModeChange?: (mode: EditMode) => void;
+    /** Override the default /api/intent endpoint. */
+    apiEndpoint?: string;
+    /** Additional CSS class applied to the root wrapper. */
+    className?: string;
+    /** Inline styles applied to the root wrapper. */
+    style?: React.CSSProperties;
+}
+declare function StudioEditor({ initialLatex, latex: controlledLatex, onMutation, editMode, voiceEnabled, onModeChange, apiEndpoint, className, style, }: StudioEditorProps): react_jsx_runtime.JSX.Element;
+
+export { type DiffEntry, type EditMode, type Intent, type IntentType, type MutationResult, StudioEditor, type StudioEditorProps };

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface Intent {
+    type: IntentType;
+    target?: {
+        role: string;
+    };
+    source?: {
+        role: string;
+    };
+    value?: {
+        raw: string;
+    };
+    term?: {
+        raw: string;
+    };
+    wrapper?: 'SQRT' | 'FRACTION';
+    operation?: 'ADD' | 'SUBTRACT' | 'MULTIPLY' | 'DIVIDE';
+    reason?: string;
+    confidence?: number;
+    source_tier?: string;
+    source_origin?: string;
+}
+type IntentType = 'REPLACE_VALUE' | 'DELETE_NODE' | 'INSERT_NODE' | 'REPARENT_NODE' | 'NEGATE_NODE' | 'WRAP_NODE' | 'APPLY_INVERSE' | 'TRANSPOSE_TERM' | 'UNKNOWN';
+
+type EditMode = 'CORRECT' | 'ALGEBRA' | 'ASK';
+interface DiffEntry {
+    op: string;
+    role?: string;
+    before?: string;
+    after?: string;
+    srcRole?: string;
+    tgtRole?: string;
+    srcVal?: string;
+    tgtVal?: string;
+    wrapper?: string;
+    operation?: string;
+    value?: string;
+    lhsBefore?: string;
+    lhsAfter?: string;
+    rhsBefore?: string;
+    rhsAfter?: string;
+    term?: string;
+    from?: string;
+    to?: string;
+    note?: string;
+}
+interface MutationResult {
+    success: boolean;
+    before: string;
+    after: string;
+    diff: DiffEntry | null;
+    error?: string;
+}
+
+interface StudioEditorProps {
+    /** Starting LaTeX string (uncontrolled). Defaults to \\frac{-b}{2a}. */
+    initialLatex?: string;
+    /** Fully-controlled LaTeX. When provided, the component renders this value
+     *  and calls onMutation on every successful edit but does not manage its
+     *  own undo stack. */
+    latex?: string;
+    /** Called after every successful mutation. */
+    onMutation?: (result: MutationResult) => void;
+    /** Edit mode to enforce. Defaults to 'CORRECT'. */
+    editMode?: EditMode;
+    /** Show / hide the microphone button. Defaults to true. */
+    voiceEnabled?: boolean;
+    /** Called when the user changes modes (only when editMode is unset). */
+    onModeChange?: (mode: EditMode) => void;
+    /** Override the default /api/intent endpoint. */
+    apiEndpoint?: string;
+    /** Additional CSS class applied to the root wrapper. */
+    className?: string;
+    /** Inline styles applied to the root wrapper. */
+    style?: React.CSSProperties;
+}
+declare function StudioEditor({ initialLatex, latex: controlledLatex, onMutation, editMode, voiceEnabled, onModeChange, apiEndpoint, className, style, }: StudioEditorProps): react_jsx_runtime.JSX.Element;
+
+export { type DiffEntry, type EditMode, type Intent, type IntentType, type MutationResult, StudioEditor, type StudioEditorProps };