0.0.245 • Published 11 months ago

@tscircuit/runframe v0.0.245

Weekly downloads
-
License
-
Repository
-
Last release
11 months ago

@tscircuit/runframe

tscircuit ⋅ View Examples

A React component that runs tscircuit inside a webworker and shows you the PCB, Schematic, 3D and other previews.

  • Automatically imports other snippets and libraries if imported
  • Runs inside webworker (doesn't block the main thread)
  • Converts typescript to javascript using babel

Usage

import { RunFrame } from "@tscircuit/runframe/runner"

const App = () => (
  <RunFrame
    fsMap={{
      "main.tsx": `
circuit.add(
  <resistor resistance="1k" />
)
`,
    }}
    entrypoint="main.tsx"

    // Listen to events
    onCircuitJsonChange={(circuitJson) => void}
    onRenderingFinished={({ circuitJson }) => void}
    onRenderEvent={(event) => void}
    onError={(error) => void}
  />
)

Using CircuitJsonPreview Directly

If you already have circuit JSON and just want to display it:

import { CircuitJsonPreview } from "@tscircuit/runframe/preview"

const App = () => (
  <CircuitJsonPreview
    circuitJson={myCircuitJson}
    // Optional props
    showCodeTab={false}      // Show/hide the code editor tab
    showJsonTab={true}       // Show/hide the raw JSON viewer tab
    className="h-screen"     // Container className
    headerClassName="px-4"   // Header className
    isFullScreen={false}     // Toggle fullscreen mode
    onToggleFullScreen={() => void}  // Fullscreen toggle callback
  />
)

The CircuitJsonPreview component provides:

  • PCB view with interactive component placement
  • Schematic view
  • Assembly view
  • 3D view
  • Bill of Materials (BOM) table
  • Circuit JSON viewer
  • Error display

Providing the Blob URL (to avoid loading webworker from CDN)

import evalWebWorkerBlobUrl from "@tscircuit/eval/blob-url"

Standalone Iframe

RunFrame can be embedded in an iframe, allowing you to evaluate tscircuit code from a parent application. There are two main ways to integrate RunFrame: using the React component or creating a standalone iframe implementation.

<!DOCTYPE html>
<html>
  <head>
    <title>RunFrame Host</title>
  </head>
  <body>
    <iframe
      id="runframe"
      src="https://runframe.tscircuit.com/iframe.html"
      style="width: 100%; height: 600px; border: none;"
    ></iframe>

    <script>
      const iframe = document.getElementById("runframe")

      // Listen for ready message from iframe
      window.addEventListener("message", (event) => {
        if (event.data?.runframe_type === "runframe_ready_to_receive") {
          // Send circuit configuration
          iframe.contentWindow.postMessage(
            {
              runframe_type: "runframe_props_changed",
              runframe_props: {
                fsMap: {
                  "main.tsx": `circuit.add(<resistor resistance="1k" />)`,
                },
                entrypoint: "main.tsx",
              },
            },
            "*"
          )
        }
      })
    </script>
  </body>
</html>

Listening for events from the iframe

window.addEventListener("message", (event) => {
  if (event.data?.runframe_type === "runframe_event") {
    const { type } = event.data.runframe_event
    if (type === "error") {
      console.error(event.data.runframe_event.error_message)
    }
  }
})

Development

File-Server Interaction with Edit Events

Edit events can be a complex to understand, because it can take some time for rendering to complete, edit events are applied for an approximate render before the circuit is fully rendered. The sequence diagram below can be used as a reference to understand how the edit events are applied and queued for rendering.

sequenceDiagram
    participant CLI
    participant FileServer as File Server
    participant BrowserRunframe as Browser Runframe
    participant Viewer as Schematic/PCB Viewer

    BrowserRunframe->>Viewer: Initial Circuit JSON

    Note over Viewer: Edit event created
    Viewer->>BrowserRunframe: onEditEvent
    Note over BrowserRunframe: newEditEvent._applied=false<br/>editEvents.push(newEditEvent)
    BrowserRunframe->>Viewer: editEvents={editEvents}

    BrowserRunframe->>FileServer: /files/get manual-edits.json
    FileServer-->>BrowserRunframe: manual-edits.json content

    Note over BrowserRunframe: Apply edit events to manual-edits.json<br/>Mark editEvent._applied = true

    BrowserRunframe->>FileServer: /files/update manual-edits.json
    FileServer->>CLI: FILE_UPDATED event

    Note over CLI: Update manual-edits.json on filesystem

    rect rgb(200, 230, 255)
        Note over BrowserRunframe: Start re-render

        Note over Viewer: Edit event created
        Viewer->>BrowserRunframe: onEditEvent
        Note over BrowserRunframe: newEditEvent._applied=false<br/>editEvents.push(newEditEvent)
        BrowserRunframe->>Viewer: editEvents={editEvents}<br/>both unapplied & applied<br/>edit events are sent

        Note over BrowserRunframe: Render complete
    end

    Note over BrowserRunframe: Remove all applied editEvents

    BrowserRunframe->>Viewer: editEvents={editEvents}<br/>circuitJson={circuitJson}<br/>Send unapplied editEvents list<br/>+ Circuit JSON

    Note over BrowserRunframe: If there are unapplied editEvents, repeat

<RunFrameWithApi /> and <RunFrameForCli /> Event Bus

The event bus for the RunFrame is accessible from the @tscircuit/file-server /events/list endpoint. RunFrame creates the following events:

Event NameDescription
FILE_UPDATEDA file was updated
REQUEST_TO_SAVE_SNIPPETBrowser request to save the current circuit to snippets
FAILED_TO_SAVE_SNIPPETFailed to save the current snippet to Registry
SNIPPET_SAVEDSnippet was saved to Registry
@radix-ui/react-alert-dialog@radix-ui/react-dropdown-menu@radix-ui/react-icons@radix-ui/react-slot@radix-ui/react-tabs@tscircuit/3d-viewer@tscircuit/assembly-viewer@tscircuit/core@tscircuit/create-snippet-url@tscircuit/eval@tscircuit/file-server@tscircuit/pcb-viewer@tscircuit/props@tscircuit/schematic-viewercircuit-to-svgclsxcomlinkcssnanojscad-fiberlucide-reactschematic-symbolstailwind-mergetailwindcss-animate
@tscircuit/snippets-cli
0.0.241

11 months ago

0.0.240

11 months ago

0.0.245

11 months ago

0.0.244

11 months ago

0.0.243

11 months ago

0.0.242

11 months ago

0.0.216

11 months ago

0.0.219

11 months ago

0.0.218

11 months ago

0.0.217

11 months ago

0.0.227

11 months ago

0.0.226

11 months ago

0.0.225

11 months ago

0.0.224

11 months ago

0.0.229

11 months ago

0.0.228

11 months ago

0.0.223

11 months ago

0.0.222

11 months ago

0.0.221

11 months ago

0.0.220

11 months ago

0.0.238

11 months ago

0.0.237

11 months ago

0.0.236

11 months ago

0.0.235

11 months ago

0.0.239

11 months ago

0.0.230

11 months ago

0.0.234

11 months ago

0.0.233

11 months ago

0.0.232

11 months ago

0.0.231

11 months ago

0.0.205

11 months ago

0.0.204

11 months ago

0.0.203

11 months ago

0.0.202

11 months ago

0.0.209

11 months ago

0.0.208

11 months ago

0.0.207

11 months ago

0.0.206

11 months ago

0.0.201

11 months ago

0.0.215

11 months ago

0.0.214

11 months ago

0.0.213

11 months ago

0.0.212

11 months ago

0.0.211

11 months ago

0.0.210

11 months ago

0.0.200

12 months ago

0.0.197

12 months ago

0.0.196

12 months ago

0.0.195

12 months ago

0.0.194

12 months ago

0.0.199

12 months ago

0.0.198

12 months ago

0.0.193

12 months ago

0.0.192

12 months ago

0.0.191

12 months ago

0.0.190

12 months ago

0.0.189

12 months ago

0.0.188

12 months ago

0.0.159

12 months ago

0.0.158

12 months ago

0.0.157

12 months ago

0.0.156

12 months ago

0.0.155

12 months ago

0.0.154

12 months ago

0.0.169

12 months ago

0.0.164

12 months ago

0.0.163

12 months ago

0.0.162

12 months ago

0.0.161

12 months ago

0.0.168

12 months ago

0.0.167

12 months ago

0.0.166

12 months ago

0.0.165

12 months ago

0.0.160

12 months ago

0.0.175

12 months ago

0.0.174

12 months ago

0.0.173

12 months ago

0.0.172

12 months ago

0.0.179

12 months ago

0.0.178

12 months ago

0.0.177

12 months ago

0.0.176

12 months ago

0.0.171

12 months ago

0.0.170

12 months ago

0.0.186

12 months ago

0.0.185

12 months ago

0.0.184

12 months ago

0.0.183

12 months ago

0.0.187

12 months ago

0.0.182

12 months ago

0.0.181

12 months ago

0.0.180

12 months ago

0.0.153

12 months ago

0.0.152

12 months ago

0.0.151

12 months ago

0.0.150

12 months ago

0.0.128

1 year ago

0.0.127

1 year ago

0.0.126

1 year ago

0.0.125

1 year ago

0.0.129

1 year ago

0.0.124

1 year ago

0.0.123

1 year ago

0.0.139

1 year ago

0.0.138

1 year ago

0.0.137

1 year ago

0.0.136

1 year ago

0.0.131

1 year ago

0.0.130

1 year ago

0.0.135

1 year ago

0.0.134

1 year ago

0.0.133

1 year ago

0.0.132

1 year ago

0.0.149

12 months ago

0.0.148

12 months ago

0.0.147

12 months ago

0.0.142

1 year ago

0.0.141

1 year ago

0.0.140

1 year ago

0.0.146

12 months ago

0.0.145

12 months ago

0.0.144

1 year ago

0.0.143

1 year ago

0.0.117

1 year ago

0.0.116

1 year ago

0.0.115

1 year ago

0.0.114

1 year ago

0.0.119

1 year ago

0.0.118

1 year ago

0.0.113

1 year ago

0.0.120

1 year ago

0.0.122

1 year ago

0.0.121

1 year ago

0.0.106

1 year ago

0.0.105

1 year ago

0.0.104

1 year ago

0.0.103

1 year ago

0.0.109

1 year ago

0.0.108

1 year ago

0.0.107

1 year ago

0.0.102

1 year ago

0.0.101

1 year ago

0.0.100

1 year ago

0.0.112

1 year ago

0.0.111

1 year ago

0.0.110

1 year ago

0.0.95

1 year ago

0.0.96

1 year ago

0.0.97

1 year ago

0.0.98

1 year ago

0.0.99

1 year ago

0.0.90

1 year ago

0.0.91

1 year ago

0.0.92

1 year ago

0.0.93

1 year ago

0.0.94

1 year ago

0.0.84

1 year ago

0.0.85

1 year ago

0.0.86

1 year ago

0.0.87

1 year ago

0.0.88

1 year ago

0.0.89

1 year ago

0.0.80

1 year ago

0.0.81

1 year ago

0.0.82

1 year ago

0.0.83

1 year ago

0.0.73

1 year ago

0.0.74

1 year ago

0.0.75

1 year ago

0.0.76

1 year ago

0.0.77

1 year ago

0.0.78

1 year ago

0.0.79

1 year ago

0.0.70

1 year ago

0.0.71

1 year ago

0.0.72

1 year ago

0.0.62

1 year ago

0.0.63

1 year ago

0.0.64

1 year ago

0.0.65

1 year ago

0.0.66

1 year ago

0.0.67

1 year ago

0.0.68

1 year ago

0.0.69

1 year ago

0.0.40

1 year ago

0.0.41

1 year ago

0.0.42

1 year ago

0.0.43

1 year ago

0.0.44

1 year ago

0.0.45

1 year ago

0.0.46

1 year ago

0.0.47

1 year ago

0.0.37

1 year ago

0.0.38

1 year ago

0.0.39

1 year ago

0.0.30

1 year ago

0.0.31

1 year ago

0.0.32

1 year ago

0.0.33

1 year ago

0.0.34

1 year ago

0.0.35

1 year ago

0.0.36

1 year ago

0.0.29

1 year ago

0.0.60

1 year ago

0.0.61

1 year ago

0.0.59

1 year ago

0.0.51

1 year ago

0.0.52

1 year ago

0.0.53

1 year ago

0.0.54

1 year ago

0.0.55

1 year ago

0.0.56

1 year ago

0.0.57

1 year ago

0.0.58

1 year ago

0.0.50

1 year ago

0.0.48

1 year ago

0.0.49

1 year ago

0.0.20

1 year ago

0.0.21

1 year ago

0.0.22

1 year ago

0.0.23

1 year ago

0.0.24

1 year ago

0.0.25

1 year ago

0.0.15

1 year ago

0.0.16

1 year ago

0.0.17

1 year ago

0.0.18

1 year ago

0.0.19

1 year ago

0.0.13

1 year ago

0.0.14

1 year ago

0.0.26

1 year ago

0.0.27

1 year ago

0.0.28

1 year ago

0.0.11

1 year ago

0.0.12

1 year ago

0.0.10

1 year ago

0.0.9

1 year ago

0.0.8

1 year ago

0.0.7

1 year ago

0.0.6

1 year ago

0.0.5

1 year ago

0.0.4

1 year ago

0.0.3

1 year ago

0.0.2

1 year ago

0.0.1

1 year ago