@dfosco/storyboard-react-primer 1.1.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@dfosco/storyboard-react-primer",
+  "version": "1.1.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dfosco/storyboard.git",
+    "directory": "packages/react-primer"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@dfosco/storyboard-react": "*"
+  },
+  "peerDependencies": {
+    "@primer/react": ">=37",
+    "react": ">=18"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  }
+}

package/src/Checkbox.jsx

@@ -0,0 +1,57 @@
+/* eslint-disable react/prop-types */
+import { useContext, useState, useEffect } from 'react'
+import { Checkbox as PrimerCheckbox } from '@primer/react'
+import { FormContext } from '@dfosco/storyboard-react'
+import { useOverride } from '@dfosco/storyboard-react'
+
+/**
+ * Wrapped Primer Checkbox that integrates with StoryboardForm.
+ *
+ * Inside a <StoryboardForm>, values are buffered locally and only
+ * written to session on form submit.
+ *
+ * Stores "true" / "false" as string values in the URL hash.
+ */
+export default function Checkbox({ name, onChange, checked: controlledChecked, ...props }) {
+  const form = useContext(FormContext)
+  const path = form?.prefix && name ? `${form.prefix}.${name}` : name
+  const [sessionValue] = useOverride(path || '')
+
+  const initialChecked = sessionValue === 'true' || sessionValue === true
+  const [draft, setDraftState] = useState(initialChecked)
+
+  const isConnected = !!form && !!name
+
+  useEffect(() => {
+    if (!isConnected) return
+    return form.subscribe(name, (val) => setDraftState(val === 'true' || val === true))
+  }, [isConnected, form, name])
+
+  useEffect(() => {
+    if (isConnected && sessionValue != null) {
+      const val = sessionValue === 'true' || sessionValue === true
+      setDraftState(val)
+      form.setDraft(name, val ? 'true' : 'false')
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const handleChange = (e) => {
+    if (isConnected) {
+      setDraftState(e.target.checked)
+      form.setDraft(name, e.target.checked ? 'true' : 'false')
+    }
+    if (onChange) onChange(e)
+  }
+
+  const resolvedChecked = isConnected ? draft : controlledChecked
+
+  return (
+    <PrimerCheckbox
+      name={name}
+      checked={resolvedChecked}
+      onChange={handleChange}
+      {...props}
+    />
+  )
+}

package/src/DevTools/DevTools.jsx

@@ -0,0 +1,140 @@
+import { useState, useEffect, useCallback } from 'react'
+import { ActionMenu, ActionList } from '@primer/react'
+import { loadScene } from '@dfosco/storyboard-core'
+import { BeakerIcon, InfoIcon, SyncIcon, XIcon, ScreenFullIcon } from '@primer/octicons-react'
+import styles from './DevTools.module.css'
+
+function getSceneName() {
+  return new URLSearchParams(window.location.search).get('scene') || 'default'
+}
+
+/**
+ * Storyboard DevTools — a floating toolbar for development.
+ *
+ * Features:
+ *  - Floating button (bottom-center) that opens a menu
+ *  - "Show scene info" — translucent overlay panel with resolved scene JSON
+ *  - "Reset all params" — clears all URL hash session params
+ *  - Cmd+. (Mac) / Ctrl+. (other) toggles the toolbar visibility
+ */
+export default function DevTools() {
+  const [visible, setVisible] = useState(true)
+  const [panelOpen, setPanelOpen] = useState(false)
+  const [sceneData, setSceneData] = useState(null)
+  const [sceneError, setSceneError] = useState(null)
+
+  // Cmd+. keyboard shortcut to toggle toolbar
+  useEffect(() => {
+    function handleKeyDown(e) {
+      if (e.key === '.' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault()
+        setVisible((v) => !v)
+        if (visible) {
+          setPanelOpen(false)
+        }
+      }
+    }
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [visible])
+
+  const handleShowSceneInfo = useCallback(() => {
+    const sceneName = getSceneName()
+    setPanelOpen(true)
+    setSceneError(null)
+
+    try {
+      setSceneData(loadScene(sceneName))
+    } catch (err) {
+      setSceneError(err.message)
+    }
+  }, [])
+
+  const handleResetParams = useCallback(() => {
+    window.location.hash = ''
+  }, [])
+
+  const handleViewfinder = useCallback(() => {
+    window.location.href = (document.querySelector('base')?.href || '/') + 'viewfinder'
+  }, [])
+
+  if (!visible) return null
+
+  return (
+    <>
+      {/* Scene info overlay panel */}
+      {panelOpen && (
+        <div className={styles.overlay}>
+          <div
+            className={styles.overlayBackdrop}
+            onClick={() => setPanelOpen(false)}
+          />
+          <div className={styles.panel}>
+            <div className={styles.panelHeader}>
+              <span className={styles.panelTitle}>
+                Scene: {getSceneName()}
+              </span>
+              <button
+                className={styles.panelClose}
+                onClick={() => setPanelOpen(false)}
+                aria-label="Close panel"
+              >
+                <XIcon size={16} />
+              </button>
+            </div>
+            <div className={styles.panelBody}>
+              {sceneError && (
+                <span className={styles.error}>{sceneError}</span>
+              )}
+              {!sceneError && sceneData && (
+                <pre className={styles.codeBlock}>
+                  {JSON.stringify(sceneData, null, 2)}
+                </pre>
+              )}
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Floating toolbar */}
+      <div className={styles.wrapper}>
+        <ActionMenu>
+          <ActionMenu.Anchor>
+            <button
+              className={styles.trigger}
+              aria-label="Storyboard DevTools"
+            >
+              <BeakerIcon className={styles.triggerIcon} size={16} />
+            </button>
+          </ActionMenu.Anchor>
+          <ActionMenu.Overlay align="center" side="outside-top" sideOffset={16}>
+            <ActionList>
+              <ActionList.Item onSelect={handleViewfinder}>
+                <ActionList.LeadingVisual>
+                  <ScreenFullIcon size={16} />
+                </ActionList.LeadingVisual>
+                See viewfinder
+              </ActionList.Item>
+              <ActionList.Item onSelect={handleShowSceneInfo}>
+                <ActionList.LeadingVisual>
+                  <InfoIcon size={16} />
+                </ActionList.LeadingVisual>
+                Show scene info
+              </ActionList.Item>
+              <ActionList.Item onSelect={handleResetParams}>
+                <ActionList.LeadingVisual>
+                  <SyncIcon size={16} />
+                </ActionList.LeadingVisual>
+                Reset all params
+              </ActionList.Item>
+              <div className={styles.shortcutHint}>
+                Press <code>⌘ + .</code> to hide
+              </div>
+              
+            </ActionList>
+          </ActionMenu.Overlay>
+        </ActionMenu>
+      </div>
+    </>
+  )
+}

package/src/DevTools/DevTools.module.css

@@ -0,0 +1,153 @@
+.wrapper {
+  position: fixed;
+  bottom: var(--base-size-24);
+  right: var(--base-size-24);
+  z-index: 9999;
+  font-family: var(--fontStack-system);
+}
+
+code {
+  font-family: var(--fontStack-monospace);
+  background-color: var(--bgColor-muted);
+  padding: 2px 4px;
+  border-radius: var(--borderRadius-small);
+
+  &:hover {
+    background-color: var(--bgColor-muted);
+  }
+}
+
+/* Floating trigger button */
+.trigger {
+  display: flex;
+  align-items: center;
+  gap: var(--base-size-8);
+  padding: var(--base-size-12);
+  background-color: var(--bgColor-subtle);
+  color: var(--fgColor-muted);
+  border: 1px solid var(--borderColor-default);
+  border-radius: var(--borderRadius-full);
+  font-size: var(--text-body-size-small);
+  font-weight: var(--base-text-weight-semibold);
+  font-family: var(--fontStack-system);
+  cursor: pointer;
+  box-shadow: var(--shadow-floating-large);
+  transition: opacity 150ms ease, transform 150ms ease;
+  user-select: none;
+}
+
+.trigger:hover {
+  transform: scale(1.05);
+}
+
+.trigger:active {
+  transform: scale(0.97);
+}
+
+.triggerIcon {
+  width: var(--base-size-16);
+  height: var(--base-size-16);
+}
+
+.shortcutHint {
+  padding: var(--base-size-8) var(--base-size-16); 
+}
+
+/* Scene info overlay panel */
+.overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 9998;
+  display: flex;
+  align-items: flex-end;
+  justify-content: center;
+  padding: var(--base-size-16);
+  padding-bottom: calc(var(--base-size-64) + var(--base-size-16));
+}
+
+.overlayBackdrop {
+  position: fixed;
+  inset: 0;
+  background: transparent;
+}
+
+.panel {
+  position: relative;
+  width: 100%;
+  max-width: 640px;
+  max-height: 60vh;
+  background-color: var(--overlay-bgColor);
+  backdrop-filter: blur(16px);
+  border: 1px solid var(--borderColor-default);
+  border-radius: var(--borderRadius-large);
+  box-shadow: var(--shadow-floating-large);
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+
+.panelHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: var(--base-size-12) var(--base-size-16);
+  border-bottom: 1px solid var(--borderColor-muted);
+}
+
+.panelTitle {
+  font-size: var(--text-body-size-medium);
+  font-weight: var(--base-text-weight-semibold);
+  color: var(--fgColor-default);
+}
+
+.panelClose {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--base-size-28);
+  height: var(--base-size-28);
+  background: none;
+  border: none;
+  border-radius: var(--borderRadius-small);
+  color: var(--fgColor-muted);
+  cursor: pointer;
+}
+
+.panelClose:hover {
+  background-color: var(--control-transparent-bgColor-hover);
+  color: var(--fgColor-default);
+}
+
+.panelBody {
+  overflow: auto;
+  padding: var(--base-size-16);
+}
+
+.codeBlock {
+  padding: 0;
+  margin: 0;
+  background: none;
+  font-size: var(--text-body-size-small);
+  font-family: var(--fontStack-monospace);
+  line-height: var(--text-body-lineHeight-medium);
+  color: var(--fgColor-default);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.error {
+  color: var(--fgColor-danger);
+}
+
+.loading {
+  color: var(--fgColor-muted);
+  font-size: var(--text-body-size-small);
+}
+
+/* Keyboard shortcut hint */
+.shortcutHint {
+  font-size: var(--text-caption-size);
+  color: var(--fgColor-muted);
+  margin-left: auto;
+  font-family: var(--fontStack-monospace);
+}

package/src/SceneDataDemo.jsx

@@ -0,0 +1,90 @@
+import { Text, Button, ButtonGroup, FormControl } from '@primer/react'
+import { useOverride } from '@dfosco/storyboard-react'
+import { useScene } from '@dfosco/storyboard-react'
+import StoryboardForm from './StoryboardForm.jsx'
+import TextInput from './TextInput.jsx'
+import Textarea from './Textarea.jsx'
+import styles from './SceneDebug.module.css'
+
+/**
+ * Demo component that renders scene data via useOverride().
+ * Every value can be overridden by adding a URL param, e.g.:
+ *   #user.name=Alice&user.profile.bio=Hello
+ * Refresh the page — overrides persist. Remove the param — scene default returns.
+ */
+export default function SceneDataDemo() {
+  const [name, setName, clearName] = useOverride('user.name')
+  const [username, setUsername, clearUsername] = useOverride('user.username')
+  const [bio, , clearBio] = useOverride('user.profile.bio')
+  const [location, , clearLocation] = useOverride('user.profile.location')
+  const { sceneName, switchScene } = useScene()
+
+  const nextScene = (sceneName === 'default') ? 'other-scene' : 'default'
+
+  const resetUser = () => {
+    clearName()
+    clearUsername()
+    clearBio()
+    clearLocation()
+  }
+
+  return (
+    <div className={styles.container}>
+      <h2 className={styles.title}>useOverride Demo</h2>
+      <p>Add <code>#user.name=Alice</code> to the URL hash to override any value.</p>
+
+      <section>
+        <Text as="h3" fontWeight="bold">Scene</Text>
+        <pre className={styles.codeBlock}>current: {sceneName}</pre>
+        
+        <Button size="small" onClick={() => switchScene(nextScene)}>
+          Switch to &quot;{nextScene}&quot;
+        </Button>
+      </section>
+
+      <section>
+        <Text as="h3" fontWeight="bold">User</Text>
+        <pre className={styles.codeBlock}>
+          {name} ({username})
+        </pre>
+        <pre className={styles.codeBlock}>
+          {bio} · {location}
+        </pre>
+
+        <Text as="h4" fontWeight="semibold" fontSize={1}>Switch User</Text>
+        <ButtonGroup>
+          <Button size="small" onClick={() => setName('Alice Chen')}>Update name</Button>
+          <Button size="small" onClick={() => setUsername('alice123')}>Update username</Button>
+        </ButtonGroup>
+        <Button size="small" variant="danger" onClick={resetUser} style={{ marginLeft: '8px' }}>
+          Reset
+        </Button>
+      </section>
+
+      <a href="/storyboard/Overview">hello</a>
+
+      <section>
+        <Text as="h3" fontWeight="bold">Edit User</Text>
+        <StoryboardForm data="user" className={styles.form}>
+          <FormControl>
+            <FormControl.Label>Name</FormControl.Label>
+            <TextInput name="name" placeholder="Name" size="small" />
+          </FormControl>
+          <FormControl>
+            <FormControl.Label>Username</FormControl.Label>
+            <TextInput name="username" placeholder="Username" size="small" />
+          </FormControl>
+          <FormControl>
+            <FormControl.Label>Bio</FormControl.Label>
+            <Textarea name="profile.bio" placeholder="Bio" />
+          </FormControl>
+          <FormControl>
+            <FormControl.Label>Location</FormControl.Label>
+            <TextInput name="profile.location" placeholder="Location" size="small" />
+          </FormControl>
+          <Button type="submit" size="small">Save</Button>
+        </StoryboardForm>
+      </section>
+    </div>
+  )
+}

package/src/SceneDebug.jsx

@@ -0,0 +1,47 @@
+import { useMemo } from 'react'
+import PropTypes from 'prop-types'
+import { useSearchParams } from 'react-router-dom'
+import { Text } from '@primer/react'
+import { loadScene } from '@dfosco/storyboard-core'
+import styles from './SceneDebug.module.css'
+
+/**
+ * Debug component that displays loaded scene data as formatted JSON.
+ * Used to verify the loader is working correctly.
+ * Reads scene name from URL param (?scene=name) or uses prop/default.
+ */
+export default function SceneDebug({ sceneName } = {}) {
+  const [searchParams] = useSearchParams()
+  const sceneFromUrl = searchParams.get('scene')
+  const activeSceneName = sceneName || sceneFromUrl || 'default'
+
+  const { data, error } = useMemo(() => {
+    try {
+      return { data: loadScene(activeSceneName), error: null }
+    } catch (err) {
+      return { data: null, error: err.message }
+    }
+  }, [activeSceneName])
+
+  if (error) {
+    return (
+      <div className={styles.error}>
+        <Text className={styles.errorTitle}>Error loading scene</Text>
+        <p className={styles.errorMessage}>{error}</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className={styles.container}>
+      <h2 className={styles.title}>Scene: {activeSceneName}</h2>
+      <pre className={styles.codeBlock}>
+        {JSON.stringify(data, null, 2)}
+      </pre>
+    </div>
+  )
+}
+
+SceneDebug.propTypes = {
+  sceneName: PropTypes.string,
+}

package/src/SceneDebug.module.css

@@ -0,0 +1,43 @@
+.container {
+  padding: var(--stack-padding-normal);
+}
+
+.title {
+  font-size: var(--text-title-size-small);
+  font-weight: var(--base-text-weight-semibold);
+  margin-bottom: var(--base-size-8);
+}
+
+.codeBlock {
+  padding: var(--stack-padding-normal);
+  background-color: var(--bgColor-muted);
+  border-radius: var(--borderRadius-medium);
+  overflow: auto;
+  font-size: var(--text-body-size-small);
+  font-family: var(--fontStack-monospace);
+  line-height: var(--text-body-lineHeight-medium);
+  max-height: 70vh;
+}
+
+.error {
+  padding: var(--stack-padding-normal);
+  background-color: var(--bgColor-danger-muted, var(--bgColor-muted));
+  border-radius: var(--borderRadius-medium);
+}
+
+.errorTitle {
+  color: var(--fgColor-danger, var(--fgColor-default));
+  font-weight: var(--base-text-weight-semibold);
+}
+
+.errorMessage {
+  color: var(--fgColor-danger, var(--fgColor-default));
+  margin-top: var(--base-size-4);
+}
+
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--stack-gap-condensed);
+  max-width: 320px;
+}

package/src/Select.jsx

@@ -0,0 +1,60 @@
+/* eslint-disable react/prop-types */
+import { useContext, useState, useEffect } from 'react'
+import { Select as PrimerSelect } from '@primer/react'
+import { FormContext } from '@dfosco/storyboard-react'
+import { useOverride } from '@dfosco/storyboard-react'
+
+/**
+ * Wrapped Primer Select that integrates with StoryboardForm.
+ *
+ * Inside a <StoryboardForm>, values are buffered locally and only
+ * written to session on form submit.
+ *
+ * Outside a form, behaves as a normal controlled Primer Select.
+ */
+export default function Select({ name, onChange, value: controlledValue, children, ...props }) {
+  const form = useContext(FormContext)
+  const path = form?.prefix && name ? `${form.prefix}.${name}` : name
+  const [sessionValue] = useOverride(path || '')
+
+  const [draft, setDraftState] = useState(sessionValue ?? '')
+
+  const isConnected = !!form && !!name
+
+  useEffect(() => {
+    if (!isConnected) return
+    return form.subscribe(name, (val) => setDraftState(val))
+  }, [isConnected, form, name])
+
+  useEffect(() => {
+    if (isConnected && sessionValue != null) {
+      setDraftState(sessionValue)
+      form.setDraft(name, sessionValue)
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const handleChange = (e) => {
+    if (isConnected) {
+      setDraftState(e.target.value)
+      form.setDraft(name, e.target.value)
+    }
+    if (onChange) onChange(e)
+  }
+
+  const resolvedValue = isConnected ? draft : controlledValue
+
+  return (
+    <PrimerSelect
+      name={name}
+      value={resolvedValue}
+      onChange={handleChange}
+      {...props}
+    >
+      {children}
+    </PrimerSelect>
+  )
+}
+
+// Forward Primer's static sub-components (e.g. Select.Option)
+Select.Option = PrimerSelect.Option

package/src/StoryboardForm.jsx

@@ -0,0 +1,63 @@
+/* eslint-disable react/prop-types */
+import { useRef, useCallback } from 'react'
+import { FormContext } from '@dfosco/storyboard-react'
+import { setParam } from '@dfosco/storyboard-core'
+
+/**
+ * A form wrapper that buffers input values locally and only
+ * persists them to session (URL hash) on submit.
+ *
+ * The `data` prop sets the root path — child inputs with a `name` prop
+ * will read/write to local draft state while typing, then flush to
+ * `data.name` in the URL hash on form submission.
+ *
+ * @example
+ * <StoryboardForm data="checkout">
+ *   <FormControl>
+ *     <FormControl.Label>Email</FormControl.Label>
+ *     <TextInput name="email" />
+ *   </FormControl>
+ *   <Button type="submit">Save</Button>
+ * </StoryboardForm>
+ * // On submit: writes #checkout.email=... to URL hash
+ */
+export default function StoryboardForm({ data, onSubmit, children, ...props }) {
+  const prefix = data || null
+  const draftsRef = useRef({})
+  const listenersRef = useRef({})
+
+  const getDraft = useCallback((name) => draftsRef.current[name], [])
+
+  const setDraft = useCallback((name, value) => {
+    draftsRef.current[name] = value
+    // Notify the field so it re-renders with the new draft value
+    const listener = listenersRef.current[name]
+    if (listener) listener(value)
+  }, [])
+
+  const subscribe = useCallback((name, listener) => {
+    listenersRef.current[name] = listener
+    return () => { delete listenersRef.current[name] }
+  }, [])
+
+  const handleSubmit = (e) => {
+    e.preventDefault()
+    // Flush all draft values to session hash params
+    if (prefix) {
+      for (const [name, value] of Object.entries(draftsRef.current)) {
+        setParam(`${prefix}.${name}`, value)
+      }
+    }
+    if (onSubmit) onSubmit(e)
+  }
+
+  const contextValue = { prefix, getDraft, setDraft, subscribe }
+
+  return (
+    <FormContext.Provider value={contextValue}>
+      <form {...props} onSubmit={handleSubmit}>
+        {children}
+      </form>
+    </FormContext.Provider>
+  )
+}

package/src/TextInput.jsx

@@ -0,0 +1,59 @@
+/* eslint-disable react/prop-types */
+import { useContext, useState, useEffect } from 'react'
+import { TextInput as PrimerTextInput } from '@primer/react'
+import { FormContext } from '@dfosco/storyboard-react'
+import { useOverride } from '@dfosco/storyboard-react'
+
+/**
+ * Wrapped Primer TextInput that integrates with StoryboardForm.
+ *
+ * Inside a <StoryboardForm>, values are buffered locally and only
+ * written to session on form submit. Session values are used as
+ * initial defaults.
+ *
+ * Outside a form, behaves as a normal controlled Primer TextInput.
+ */
+export default function TextInput({ name, onChange, value: controlledValue, ...props }) {
+  const form = useContext(FormContext)
+  const path = form?.prefix && name ? `${form.prefix}.${name}` : name
+  const [sessionValue] = useOverride(path || '')
+
+  // Local draft state, initialised from session/scene default
+  const [draft, setDraftState] = useState(sessionValue ?? '')
+
+  const isConnected = !!form && !!name
+
+  // Subscribe to form context draft updates (e.g. external resets)
+  useEffect(() => {
+    if (!isConnected) return
+    return form.subscribe(name, (val) => setDraftState(val))
+  }, [isConnected, form, name])
+
+  // Sync initial session value into draft on mount
+  useEffect(() => {
+    if (isConnected && sessionValue != null) {
+      setDraftState(sessionValue)
+      form.setDraft(name, sessionValue)
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const handleChange = (e) => {
+    if (isConnected) {
+      setDraftState(e.target.value)
+      form.setDraft(name, e.target.value)
+    }
+    if (onChange) onChange(e)
+  }
+
+  const resolvedValue = isConnected ? draft : controlledValue
+
+  return (
+    <PrimerTextInput
+      name={name}
+      value={resolvedValue}
+      onChange={handleChange}
+      {...props}
+    />
+  )
+}

package/src/Textarea.jsx

@@ -0,0 +1,55 @@
+/* eslint-disable react/prop-types */
+import { useContext, useState, useEffect } from 'react'
+import { Textarea as PrimerTextarea } from '@primer/react'
+import { FormContext } from '@dfosco/storyboard-react'
+import { useOverride } from '@dfosco/storyboard-react'
+
+/**
+ * Wrapped Primer Textarea that integrates with StoryboardForm.
+ *
+ * Inside a <StoryboardForm>, values are buffered locally and only
+ * written to session on form submit.
+ *
+ * Outside a form, behaves as a normal controlled Primer Textarea.
+ */
+export default function Textarea({ name, onChange, value: controlledValue, ...props }) {
+  const form = useContext(FormContext)
+  const path = form?.prefix && name ? `${form.prefix}.${name}` : name
+  const [sessionValue] = useOverride(path || '')
+
+  const [draft, setDraftState] = useState(sessionValue ?? '')
+
+  const isConnected = !!form && !!name
+
+  useEffect(() => {
+    if (!isConnected) return
+    return form.subscribe(name, (val) => setDraftState(val))
+  }, [isConnected, form, name])
+
+  useEffect(() => {
+    if (isConnected && sessionValue != null) {
+      setDraftState(sessionValue)
+      form.setDraft(name, sessionValue)
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const handleChange = (e) => {
+    if (isConnected) {
+      setDraftState(e.target.value)
+      form.setDraft(name, e.target.value)
+    }
+    if (onChange) onChange(e)
+  }
+
+  const resolvedValue = isConnected ? draft : controlledValue
+
+  return (
+    <PrimerTextarea
+      name={name}
+      value={resolvedValue}
+      onChange={handleChange}
+      {...props}
+    />
+  )
+}

package/src/index.js

@@ -0,0 +1,16 @@
+/**
+ * @dfosco/storyboard-react-primer — Primer React design system package for Storyboard.
+ *
+ * Provides storyboard-aware form components backed by Primer React,
+ * plus dev tools styled with Primer.
+ */
+
+// Storyboard form wrappers (Primer-backed)
+export { default as TextInput } from './TextInput.jsx'
+export { default as Select } from './Select.jsx'
+export { default as Checkbox } from './Checkbox.jsx'
+export { default as Textarea } from './Textarea.jsx'
+export { default as StoryboardForm } from './StoryboardForm.jsx'
+
+// Scene data demo
+export { default as SceneDataDemo } from './SceneDataDemo.jsx'