\n );\n}\n```\n\n### Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `initialFiles` | `Record` | - | Initial file contents |\n| `initialState` | `Partial` | - | Full initial state |\n| `layout` | `'single' \\| 'multi'` | `'multi'` | Layout mode |\n| `defaultFocus` | `'editor' \\| 'viewer' \\| 'customizer'` | `'editor'` | Default focused panel |\n| `libraries` | `LibraryConfig[]` | - | Custom library configurations |\n| `onStateChange` | `(state: State) => void` | - | State change callback |\n| `onRender` | `(output: any) => void` | - | Render complete callback |\n| `onError` | `(error: Error) => void` | - | Error callback |\n| `statePersister` | `StatePersister` | - | Custom state persistence |\n| `className` | `string` | - | CSS class for container |\n| `style` | `React.CSSProperties` | - | Inline styles for container |\n| `customizerValues` | `CustomizerValuesInput` | - | Override customizer parameter values |\n| `onCustomizerValuesChange` | `(values: CustomizerValues) => void` | - | Callback when values change |\n| `onParametersChange` | `(parameters: Parameter[]) => void` | - | Callback when parameter schema changes |\n\n### Required Assets\n\nYou need to host these files publicly (available in the `public/` folder):\n\n1. **OpenSCAD WASM** (~10MB)\n - `public/wasm/openscad.js`\n - `public/wasm/openscad.wasm`\n\n2. **External Libraries**\n - `public/browserfs.min.js` - Virtual filesystem\n - `public/model-viewer.min.js` - 3D viewer\n\n3. **OpenSCAD Libraries** (optional)\n - `public/libraries/*.zip` - 20+ OpenSCAD libraries\n\n4. **Other Assets**\n - `public/fonts/` - Font files\n - `public/axes.glb` - 3D axes model\n - `public/skybox-lights.jpg` - Environment lighting\n\n## Development\n\n### Project Structure\n\n```\nopenscad-component/\n├── src/ # Source code\n├── demo/ # Demo app (npm run dev)\n├── test-app/ # Test consumer app\n├── public/ # Static assets\n└── dist/ # Built package\n```\n\n### Commands\n\n```bash\n# Development (runs demo app)\nnpm run dev\n\n# Build the component\nnpm run build\n\n# Build with watch mode\nnpm run build:watch\n```\n\n### Testing the Built Package\n\n```bash\n# Build and setup test app\nbash scripts/build-and-test.sh\n\n# Run test app\ncd test-app\nnpm run dev # Opens on port 3001\n```\n\n## Advanced Usage\n\n### Custom Customizer Panel\n\nBuild your own customizer UI by using the `customizerValues`, `onCustomizerValuesChange`, and `onParametersChange` props. This allows you to create a completely custom parameter interface while the playground handles rendering.\n\n#### Types\n\n```typescript\n// Simple input format for setting values\ntype CustomizerValuesInput = Record;\n\n// Rich output format with full metadata\ntype CustomizerValues = Record;\n\n// Parameter schema from OpenSCAD file\ntype Parameter = {\n name: string;\n type: 'number' | 'string' | 'boolean';\n initial: number | string | boolean | number[];\n group: string;\n caption?: string;\n min?: number;\n max?: number;\n step?: number;\n options?: { name: string; value: number | string }[];\n};\n```\n\n#### Example `onParametersChange` Payload\n\n```json\n[\n { \"name\": \"width\", \"type\": \"number\", \"initial\": 20, \"group\": \"Dimensions\", \"min\": 1, \"max\": 100 },\n { \"name\": \"height\", \"type\": \"number\", \"initial\": 10, \"group\": \"Dimensions\" },\n { \"name\": \"rounded\", \"type\": \"boolean\", \"initial\": true, \"group\": \"Options\" },\n { \"name\": \"style\", \"type\": \"string\", \"initial\": \"modern\", \"group\": \"Options\",\n \"options\": [{ \"name\": \"Modern\", \"value\": \"modern\" }, { \"name\": \"Classic\", \"value\": \"classic\" }] }\n]\n```\n\n#### Example\n\n```tsx\nimport { OpenSCADPlayground } from 'openscad-playground';\nimport type { CustomizerValues, CustomizerValuesInput, Parameter } from 'openscad-playground';\nimport { useState, useCallback } from 'react';\n\nfunction CustomCustomizerApp() {\n // Parameter schema from the OpenSCAD file\n const [parameters, setParameters] = useState([]);\n // Current values with full metadata\n const [values, setValues] = useState({});\n // Your overrides to send back to the playground\n const [overrides, setOverrides] = useState({});\n\n const handleChange = useCallback((name: string, value: number | string | boolean) => {\n setOverrides(prev => ({ ...prev, [name]: value }));\n }, []);\n\n // Group parameters by their /* [Group] */ annotations\n const grouped = parameters.reduce((acc, param) => {\n (acc[param.group] ??= []).push(param);\n return acc;\n }, {} as Record);\n\n return (\n
\n {/* Your custom UI */}\n \n\n {/* Playground with bindings */}\n
\n \n
\n
\n );\n}\n```\n\n#### How It Works\n\n1. **`onParametersChange`** fires when the OpenSCAD file is parsed, providing the parameter schema with types, groups, and constraints\n2. **`onCustomizerValuesChange`** fires whenever values change, providing the current state with full metadata\n3. **`customizerValues`** accepts simple key-value pairs to override parameter values - changes trigger instant re-renders\n\nThe OpenSCAD `/* [Group Name] */` syntax is used to organize parameters into groups in your custom UI.\n\n### Custom State Management\n\n```tsx\nimport { OpenSCADPlayground, State } from 'openscad-playground';\nimport { useState } from 'react';\n\nfunction App() {\n const [state, setState] = useState>({\n params: {\n activePath: 'main.scad',\n sources: [\n { path: 'main.scad', content: 'cube([10,10,10]);' }\n ]\n }\n });\n\n return (\n {\n setState(newState);\n // Save to localStorage, database, etc.\n }}\n />\n );\n}\n```\n\n### Using Hooks\n\n```tsx\nimport { useOpenSCAD } from 'openscad-playground';\n\nfunction MyComponent() {\n const { model, fs, isReady, error } = useOpenSCAD({\n initialState: getInitialState()\n });\n\n if (!isReady) return
Loading...
;\n if (error) return
Error: {error.message}
;\n\n return
OpenSCAD is ready!
;\n}\n```\n\n\n## Credits\n\n- Original OpenSCAD Playground by [Olivier Chafik](https://github.com/ochafik)\n- OpenSCAD project: [openscad.org](https://openscad.org)\n- BOSL2 and other bundled libraries by their respective authors\n","readmeFilename":"README.md"}