@westopp/windo 0.1.0

package/src/client/icons.tsx

@@ -0,0 +1,110 @@
+// Inline SVG glyphs for the chrome UI, ported from the mock workbench
+// (app.jsx WbIcons, inspector.jsx InspIcons, canvas.jsx toolbar svgs).
+// camelCase SVG attributes throughout; consumers read Icons[name].
+
+import type { ReactElement } from 'react'
+
+export const Icons: Record<string, ReactElement> = {
+  sun: (
+    <svg aria-hidden="true" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <circle cx="12" cy="12" r="4" />
+      <path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" />
+    </svg>
+  ),
+  moon: (
+    <svg aria-hidden="true" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8Z" />
+    </svg>
+  ),
+  search: (
+    <svg aria-hidden="true" width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <circle cx="11" cy="11" r="8" />
+      <path d="m21 21-4.35-4.35" />
+    </svg>
+  ),
+  chevsLeft: (
+    <svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="m11 17-5-5 5-5" />
+      <path d="m18 17-5-5 5-5" />
+    </svg>
+  ),
+  chevsRight: (
+    <svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="m6 17 5-5-5-5" />
+      <path d="m13 17 5-5-5-5" />
+    </svg>
+  ),
+  chevDown: (
+    <svg aria-hidden="true" width="9" height="9" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="3" strokeLinecap="round" strokeLinejoin="round">
+      <path d="m6 9 6 6 6-6" />
+    </svg>
+  ),
+  chevsUp: (
+    <svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="m17 18-5-5-5 5" />
+      <path d="m17 11-5-5-5 5" />
+    </svg>
+  ),
+  chevsDown: (
+    <svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="m7 6 5 5 5-5" />
+      <path d="m7 13 5 5 5-5" />
+    </svg>
+  ),
+  copy: (
+    <svg aria-hidden="true" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <rect x="9" y="9" width="11" height="11" rx="2" />
+      <path d="M5 15V5a2 2 0 0 1 2-2h10" />
+    </svg>
+  ),
+  check: (
+    <svg aria-hidden="true" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round">
+      <path d="m5 13 4 4L19 7" />
+    </svg>
+  ),
+  grid: (
+    <svg aria-hidden="true" width="15" height="15" viewBox="0 0 24 24" fill="currentColor">
+      <circle cx="5" cy="5" r="1.6" />
+      <circle cx="12" cy="5" r="1.6" />
+      <circle cx="19" cy="5" r="1.6" />
+      <circle cx="5" cy="12" r="1.6" />
+      <circle cx="12" cy="12" r="1.6" />
+      <circle cx="19" cy="12" r="1.6" />
+      <circle cx="5" cy="19" r="1.6" />
+      <circle cx="12" cy="19" r="1.6" />
+      <circle cx="19" cy="19" r="1.6" />
+    </svg>
+  ),
+  zoomIn: (
+    <svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round">
+      <path d="M12 5v14M5 12h14" />
+    </svg>
+  ),
+  zoomOut: (
+    <svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round">
+      <path d="M5 12h14" />
+    </svg>
+  ),
+  settings: (
+    <svg aria-hidden="true" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round">
+      <path d="M4 8h10M18 8h2M4 16h2M10 16h10" />
+      <circle cx="16" cy="8" r="2" />
+      <circle cx="8" cy="16" r="2" />
+    </svg>
+  ),
+  minus: (
+    <svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round">
+      <path d="M5 12h14" />
+    </svg>
+  ),
+  plus: (
+    <svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round">
+      <path d="M12 5v14M5 12h14" />
+    </svg>
+  ),
+  close: (
+    <svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M18 6 6 18M6 6l12 12" />
+    </svg>
+  ),
+}

package/src/client/index.ts

@@ -0,0 +1,15 @@
+// Chrome mount entry. Boots the workbench shell into #root.
+
+import './chrome.css'
+import { createElement } from 'react'
+import { createRoot } from 'react-dom/client'
+import { App } from './App'
+
+let root = document.getElementById('root')
+if (!root) {
+  root = document.createElement('div')
+  root.id = 'root'
+  document.body.appendChild(root)
+}
+
+createRoot(root).render(createElement(App))

package/src/client/internal-types.ts

@@ -0,0 +1,147 @@
+// Internal contracts shared across the chrome UI. App owns global state and the
+// bridge; Sidebar / Canvas / Inspector are pure-ish views driven by these props.
+// Authored up front so the components can be built independently without drift.
+
+import type { RefObject } from 'react'
+import type { WindoActionMeta, WindoContextMeta, WindoEnvState, WindoFieldError, WindoGroup, WindoLogEntry, WindoManifestEntry, WindoPropDoc, WindoSchemaDescriptor, WindoVariantMeta } from '../types'
+
+/** A log entry plus a monotonic key for stable React list rendering (the wire entry carries no unique id). */
+export interface WindoLogRow extends WindoLogEntry {
+  seq: number
+}
+
+/** The "describe" payload for the currently-selected windo. */
+export interface WindoDescribe {
+  id: string
+  descriptor: WindoSchemaDescriptor
+  props: WindoPropDoc[]
+  variants: WindoVariantMeta[]
+  defaults: unknown
+  code: string | null
+}
+
+/**
+ * Host-side bridge returned by `useWindoBridge(iframeRef)`. It owns the
+ * postMessage conversation with the preview iframe: sends host messages,
+ * subscribes to preview messages, and surfaces the latest state.
+ */
+export interface BridgeApi {
+  ready: boolean
+  /** Increments each time the preview (re)signals ready — e.g. after an HMR or dep-optimize reload. The chrome re-syncs selection/props/env when it changes. */
+  readyNonce: number
+  title: string
+  groups: WindoGroup[]
+  contexts: WindoContextMeta[]
+  manifest: WindoManifestEntry[]
+  /** describe payload for the most recently selected id (null until it arrives). */
+  describe: WindoDescribe | null
+  parseErrors: WindoFieldError[]
+  renderError: { message: string; stack?: string } | null
+  logs: WindoLogRow[]
+  clearLogs: () => void
+  /** Latest component-local state snapshot per windo id, echoed from the preview. */
+  stateValues: Record<string, Record<string, unknown>>
+  /** Live `disabled` flag per action id (keyed windo id → action id), echoed from the preview. */
+  actionDisabled: Record<string, Record<string, boolean>>
+  // outbound
+  select: (id: string) => void
+  setProps: (id: string, json: string) => void
+  setEnv: (env: WindoEnvState) => void
+  invokeAction: (id: string, actionId: string) => void
+}
+
+export type InspectorPosition = 'right' | 'bottom'
+
+export type ThemeMode = 'light' | 'dark'
+
+/** Cosmetic canvas chrome (drawn behind a transparent iframe), persisted to localStorage. */
+export interface CanvasGridOpts {
+  on: boolean
+  style: 'dots' | 'lines'
+  dotSize: number
+  gridOpacity: number
+  light: { bg: string; dot: string }
+  dark: { bg: string; dot: string }
+}
+
+export const CANVAS_GRID_DEFAULTS: CanvasGridOpts = {
+  on: true,
+  style: 'dots',
+  dotSize: 20,
+  gridOpacity: 100,
+  light: { bg: '#ffffff', dot: '#e2e2e4' },
+  dark: { bg: '#161618', dot: '#2c2c30' },
+}
+
+/** Global ambient environment edited from the chrome (Context tab + topbar theme toggle). */
+export interface ChromeEnv {
+  colorScheme: ThemeMode
+  reducedMotion: boolean
+  direction: 'ltr' | 'rtl'
+  locale: string
+  /** Per-context control values, keyed by context name then control key. */
+  contexts: Record<string, Record<string, unknown>>
+}
+
+export interface SidebarProps {
+  groups: WindoGroup[]
+  manifest: WindoManifestEntry[]
+  selected: string | null
+  onSelect: (id: string) => void
+  query: string
+  setQuery: (q: string) => void
+  collapsed: boolean
+  onToggle: () => void
+}
+
+export interface CanvasProps {
+  iframeRef: RefObject<HTMLIFrameElement | null>
+  iframeSrc: string
+  theme: ThemeMode
+  width: number
+  setWidth: (w: number) => void
+  /** null = fill available height. */
+  height: number | null
+  setHeight: (h: number | null) => void
+  zoom: number
+  setZoom: (z: number) => void
+  grid: CanvasGridOpts
+  /** patch === null resets to defaults. */
+  setGrid: (patch: Partial<CanvasGridOpts> | null) => void
+  /** `click` actions for the selected windo, rendered as toolbar buttons. */
+  actions: WindoActionMeta[]
+  /** Live `disabled` flag per action id for the selected windo. */
+  actionDisabled: Record<string, boolean>
+  onAction: (actionId: string) => void
+}
+
+export interface InspectorProps {
+  entry: WindoManifestEntry | null
+  describe: WindoDescribe | null
+  /** Preview iframe URL — variant cells each load their own to render live. */
+  iframeSrc: string
+  /** Current draft JSON in the Controls editor (App owns the value, per selected id). */
+  valuesJson: string
+  setValuesJson: (json: string) => void
+  /** True when the draft differs from what was last pushed to the preview (gates Save). */
+  dirty: boolean
+  /** Commit the current draft (host → preview → parse). */
+  onSave: () => void
+  onReset: () => void
+  parseErrors: WindoFieldError[]
+  renderError: { message: string; stack?: string } | null
+  logs: WindoLogRow[]
+  clearLogs: () => void
+  /** Live component-local state snapshot for the selected windo (drives the read-only State strip). */
+  state: Record<string, unknown>
+  /** Context metadata filtered to this windo (its `uses` providers + all ambient). */
+  contexts: WindoContextMeta[]
+  env: ChromeEnv
+  setEnv: (patch: Partial<ChromeEnv>) => void
+  setContextValue: (contextName: string, key: string, value: unknown) => void
+  /** Apply a variant patch into the editor + commit. */
+  onApplyVariant: (props: Record<string, unknown>) => void
+  position: InspectorPosition
+  collapsed: boolean
+  onToggle: () => void
+}

package/src/client/persist.ts

@@ -0,0 +1,38 @@
+// localStorage helpers. Every access is try/catch wrapped so corrupted JSON or
+// an unavailable storage backend (private mode, quota) degrades to the fallback
+// instead of throwing. Callers pass keys already prefixed with `windo:`.
+
+export function loadJSON<T>(key: string, fallback: T): T {
+  try {
+    const raw = localStorage.getItem(key)
+    if (raw === null) return fallback
+    return JSON.parse(raw) as T
+  } catch {
+    return fallback
+  }
+}
+
+export function saveJSON(key: string, value: unknown): void {
+  try {
+    localStorage.setItem(key, JSON.stringify(value))
+  } catch {
+    /* unavailable or over quota — ignore */
+  }
+}
+
+export function loadString(key: string, fallback: string): string {
+  try {
+    const raw = localStorage.getItem(key)
+    return raw === null ? fallback : raw
+  } catch {
+    return fallback
+  }
+}
+
+export function saveString(key: string, value: string): void {
+  try {
+    localStorage.setItem(key, value)
+  } catch {
+    /* unavailable or over quota — ignore */
+  }
+}

package/src/define-config.ts

@@ -0,0 +1,54 @@
+// The authoring API. `defineWindoConfig` is the single entry point: it captures
+// the project's groups + contexts and hands back a `windo` factory whose `group`
+// field is type-checked against the configured slugs.
+
+import type { ComponentType, ReactNode } from 'react'
+import type { z } from 'zod'
+import type { WindoConfig, WindoContextDefinition, WindoContextMap, WindoControlMap, WindoControlValues, WindoDefinition, WindoFactoryArg, WindoGroup, WindoModule, WindoRenderContext } from './types'
+
+export interface DefineWindoConfigResult<Groups extends readonly WindoGroup[], Contexts extends WindoContextMap> {
+  config: WindoConfig<Groups, Contexts>
+  windo: <Props, State = Record<string, never>>(factory: (w: WindoFactoryArg<Groups, Contexts>) => WindoDefinition<Props, State, Groups[number]['slug']>) => WindoModule<Props, State>
+}
+
+export function defineWindoConfig<const Groups extends readonly WindoGroup[], Contexts extends WindoContextMap = Record<string, never>>(
+  config: WindoConfig<Groups, Contexts>
+): DefineWindoConfigResult<Groups, Contexts> {
+  function windo<Props, State = Record<string, never>>(factory: (w: WindoFactoryArg<Groups, Contexts>) => WindoDefinition<Props, State, Groups[number]['slug']>): WindoModule<Props, State> {
+    return {
+      __windo: true,
+      resolve: w => factory(w as unknown as WindoFactoryArg<Groups, Contexts>),
+    }
+  }
+  return { config, windo }
+}
+
+/**
+ * Define a named context. A context can contribute ambient `controls` (values +
+ * UI), a `provider` (mounted inside the iframe for components that opt in via
+ * `uses`), or both.
+ *
+ * No cast: `def` is already structurally a `WindoContextDefinition<WindoControlValues<C>,
+ * Provided>` (only `controls` widens, covariantly). The unavoidable variance — TS has
+ * no existential type to hold contexts heterogeneous in `C` — is absorbed once, in
+ * `WindoContextMap`, not here and not at call sites.
+ */
+export function defineContext<C extends WindoControlMap, Provided = WindoControlValues<C>>(def: {
+  label?: string
+  description?: string
+  controls?: C
+  provider?: ComponentType<{ children: ReactNode; values: WindoControlValues<C>; ctx: WindoRenderContext }>
+  resolve?: (values: WindoControlValues<C>, ctx: WindoRenderContext) => Provided
+}): WindoContextDefinition<WindoControlValues<C>, Provided> {
+  return def
+}
+
+/**
+ * Bind a zod schema to a component's props. The generic carries the component's
+ * prop type so the schema's output stays a subset of it; the returned schema is
+ * the runtime validator + parser (`z.input` is the JSON edit surface, `z.output`
+ * is what the component receives).
+ */
+export function configurableProps<P>() {
+  return <S extends z.ZodType<Partial<P>>>(schema: S): S => schema
+}

package/src/descriptor.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { describeSchema } from './descriptor'
+import type { WindoControlDescriptor } from './types'
+
+function field(fields: WindoControlDescriptor[], key: string): WindoControlDescriptor {
+  const found = fields.find(f => f.key === key)
+  if (!found) throw new Error(`no field "${key}"`)
+  return found
+}
+
+describe('describeSchema', () => {
+  it('returns no fields for a missing schema', () => {
+    expect(describeSchema(undefined).fields).toEqual([])
+    expect(describeSchema(null).fields).toEqual([])
+  })
+
+  it('describes a z.enum as kind enum with the right options', () => {
+    const { fields } = describeSchema(z.object({ variant: z.enum(['primary', 'secondary', 'ghost']) }))
+    const variant = field(fields, 'variant')
+    expect(variant.kind).toBe('enum')
+    expect(variant.options).toEqual(['primary', 'secondary', 'ghost'])
+  })
+
+  it('describes a z.boolean as kind boolean', () => {
+    const { fields } = describeSchema(z.object({ disabled: z.boolean() }))
+    expect(field(fields, 'disabled').kind).toBe('boolean')
+  })
+
+  it('describes a bounded z.number with min and max', () => {
+    const { fields } = describeSchema(z.object({ count: z.number().min(0).max(10) }))
+    const count = field(fields, 'count')
+    expect(count.kind).toBe('number')
+    expect(count.min).toBe(0)
+    expect(count.max).toBe(10)
+  })
+
+  it('marks an optional field as optional', () => {
+    const { fields } = describeSchema(z.object({ label: z.string().optional() }))
+    const label = field(fields, 'label')
+    expect(label.kind).toBe('string')
+    expect(label.optional).toBe(true)
+  })
+
+  it('marks a required field as not optional', () => {
+    const { fields } = describeSchema(z.object({ label: z.string() }))
+    expect(field(fields, 'label').optional).toBe(false)
+  })
+
+  it('describes a z.coerce.date as kind date', () => {
+    const { fields } = describeSchema(z.object({ when: z.coerce.date() }))
+    expect(field(fields, 'when').kind).toBe('date')
+  })
+
+  it('describes a z.array as kind array', () => {
+    const { fields } = describeSchema(z.object({ tags: z.array(z.string()) }))
+    expect(field(fields, 'tags').kind).toBe('array')
+  })
+})

package/src/descriptor.ts

@@ -0,0 +1,185 @@
+// Walk a zod schema into a serialisable descriptor that can cross the iframe
+// boundary and render the Controls/Schema UI. We lean on `z.toJSONSchema` (zod
+// v4) for the input shape (enum options, min/max, optionality), then enrich the
+// kind from the zod node's own type tag — some types (Date, Map, Set) are
+// unrepresentable in JSON Schema and come back as `{}`, but their zod `def.type`
+// is exact. The live schema (with transforms/coerce/refine) stays in the iframe
+// and does the actual parsing — only this descriptor travels.
+
+import { z } from 'zod'
+import type { WindoControlDescriptor, WindoControlKind, WindoSchemaDescriptor } from './types'
+
+interface JsonNode {
+  type?: string | string[]
+  enum?: unknown[]
+  const?: unknown
+  format?: string
+  properties?: Record<string, JsonNode>
+  required?: string[]
+  items?: JsonNode
+  anyOf?: JsonNode[]
+  oneOf?: JsonNode[]
+  allOf?: JsonNode[]
+  minimum?: number
+  maximum?: number
+  description?: string
+}
+
+export function describeSchema(schema: z.ZodType | undefined | null): WindoSchemaDescriptor {
+  if (!schema) return { fields: [] }
+  let json: JsonNode
+  try {
+    json = z.toJSONSchema(schema, { io: 'input', unrepresentable: 'any' }) as JsonNode
+  } catch {
+    return { fields: [] }
+  }
+  const root = unwrap(json)
+  const properties = root.properties ?? {}
+  const required = new Set(root.required ?? [])
+  const zodKinds = shapeKinds(schema)
+  const fields: WindoControlDescriptor[] = Object.keys(properties).map(key => fieldFrom(key, properties[key], required.has(key), zodKinds[key]))
+  return { fields }
+}
+
+// JSON Schema often wraps the object in anyOf (for optional/nullable). Find the
+// node that actually carries the object's properties.
+function unwrap(node: JsonNode): JsonNode {
+  if (node.properties) return node
+  const branches = node.anyOf ?? node.oneOf ?? node.allOf
+  if (branches) {
+    const withProps = branches.find(b => b.properties)
+    if (withProps) return withProps
+  }
+  return node
+}
+
+function fieldFrom(key: string, node: JsonNode, isRequired: boolean, zodKind?: WindoControlKind): WindoControlDescriptor {
+  const inner = collapseNullable(node)
+  let kind = kindOf(inner)
+  // The zod tag wins for types JSON Schema can't express (date/array/object that
+  // came back as {}), and as a fallback whenever the JSON kind is unknown.
+  if (zodKind && (kind === 'unknown' || zodKind === 'date')) kind = zodKind
+  const descriptor: WindoControlDescriptor = {
+    key,
+    kind,
+    optional: !isRequired || isNullable(node),
+  }
+  if (inner.description) descriptor.description = inner.description
+  const options = enumOptions(inner)
+  if (options) descriptor.options = options
+  if (typeof inner.minimum === 'number') descriptor.min = inner.minimum
+  if (typeof inner.maximum === 'number') descriptor.max = inner.maximum
+  return descriptor
+}
+
+function isNullable(node: JsonNode): boolean {
+  const branches = node.anyOf ?? node.oneOf
+  if (!branches) return false
+  return branches.some(b => b.type === 'null')
+}
+
+// Strip a `{ anyOf: [T, null] }` wrapper down to T.
+function collapseNullable(node: JsonNode): JsonNode {
+  const branches = node.anyOf ?? node.oneOf
+  if (!branches) return node
+  const nonNull = branches.filter(b => b.type !== 'null')
+  if (nonNull.length === 1) return nonNull[0]
+  return node
+}
+
+function enumOptions(node: JsonNode): string[] | undefined {
+  if (Array.isArray(node.enum)) return node.enum.map(v => String(v))
+  const branches = node.anyOf ?? node.oneOf
+  if (branches?.every(b => b.const !== undefined)) {
+    return branches.map(b => String(b.const))
+  }
+  return undefined
+}
+
+function kindOf(node: JsonNode): WindoControlKind {
+  if (Array.isArray(node.enum) || (node.anyOf?.every(b => b.const !== undefined) ?? false)) return 'enum'
+  if (node.format === 'date-time' || node.format === 'date') return 'date'
+  const type = Array.isArray(node.type) ? node.type.find(t => t !== 'null') : node.type
+  switch (type) {
+    case 'string':
+      return 'string'
+    case 'number':
+    case 'integer':
+      return 'number'
+    case 'boolean':
+      return 'boolean'
+    case 'array':
+      return 'array'
+    case 'object':
+      return 'object'
+    default:
+      return 'unknown'
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * zod node introspection (the kind source of truth for unrepresentable types)
+ * ------------------------------------------------------------------ */
+
+interface ZodDefLike {
+  type?: string
+  innerType?: unknown
+}
+
+function zodDef(node: unknown): ZodDefLike | undefined {
+  const n = node as { def?: ZodDefLike; _zod?: { def?: ZodDefLike } } | null
+  if (!n || typeof n !== 'object') return undefined
+  return n.def ?? n._zod?.def
+}
+
+const ZOD_WRAPPERS = new Set(['optional', 'nullable', 'default', 'prefault', 'catch', 'readonly', 'nonoptional', 'lazy'])
+
+// Unwrap optional/nullable/default/... down to the meaningful inner node.
+function unwrapZodDef(node: unknown): ZodDefLike | undefined {
+  let def = zodDef(node)
+  let guard = 0
+  while (def && def.innerType && ZOD_WRAPPERS.has(def.type ?? '') && guard++ < 16) {
+    def = zodDef(def.innerType)
+  }
+  return def
+}
+
+function mapZodType(type: string | undefined): WindoControlKind | undefined {
+  switch (type) {
+    case 'date':
+      return 'date'
+    case 'string':
+      return 'string'
+    case 'number':
+    case 'int':
+    case 'bigint':
+      return 'number'
+    case 'boolean':
+      return 'boolean'
+    case 'array':
+    case 'set':
+    case 'tuple':
+      return 'array'
+    case 'object':
+    case 'record':
+    case 'map':
+      return 'object'
+    case 'enum':
+    case 'literal':
+      return 'enum'
+    default:
+      return undefined
+  }
+}
+
+// Per-field kind read straight from the zod object's shape.
+function shapeKinds(schema: z.ZodType): Record<string, WindoControlKind> {
+  const shape = (schema as { shape?: Record<string, unknown> }).shape
+  if (!shape || typeof shape !== 'object') return {}
+  const out: Record<string, WindoControlKind> = {}
+  for (const key of Object.keys(shape)) {
+    const kind = mapZodType(unwrapZodDef(shape[key])?.type)
+    if (kind) out[key] = kind
+  }
+  return out
+}

package/src/globals.d.ts

@@ -0,0 +1,9 @@
+export {}
+
+declare global {
+  // Injected by the windo Vite plugin via `define`. Tells the chrome where to
+  // load the preview iframe from: a routeless path in dev (the dev middleware
+  // serves it), a real `.html` file in a static build. Undefined when the chrome
+  // is bundled without the plugin.
+  const __WINDO_IFRAME_SRC__: string | undefined
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+// Public authoring API. This is the isomorphic entry point users import from
+// their `*.windo.tsx` and `windo.config.ts` files. No DOM or Node code lives
+// here — the chrome (`/client`), preview (`/preview`), plugin (`/plugin`), and
+// CLI (`bin`) are separate entry points.
+
+export type { DefineWindoConfigResult } from './define-config'
+export { configurableProps, defineContext, defineWindoConfig } from './define-config'
+export { describeSchema } from './descriptor'
+export type { WindoHostMessage, WindoMessage, WindoPreviewMessage } from './protocol'
+export {
+  isHostMessage,
+  isPreviewMessage,
+  isWindoMessage,
+  WINDO_MSG,
+} from './protocol'
+export type {
+  WindoAction,
+  WindoActionMeta,
+  WindoActionTrigger,
+  WindoConfig,
+  WindoContextControlMeta,
+  WindoContextDefinition,
+  WindoContextMap,
+  WindoContextMeta,
+  WindoControlDescriptor,
+  WindoControlKind,
+  WindoControlMap,
+  WindoControlSpec,
+  WindoControlType,
+  WindoControlValues,
+  WindoDefaultProps,
+  WindoDefinition,
+  WindoEnvState,
+  WindoFactoryArg,
+  WindoFieldError,
+  WindoGroup,
+  WindoLogEntry,
+  WindoLogger,
+  WindoManifestEntry,
+  WindoModule,
+  WindoPlacement,
+  WindoPropDoc,
+  WindoRenderContext,
+  WindoSchemaDescriptor,
+  WindoStatus,
+  WindoVariant,
+  WindoVariantMeta,
+  WindoViewport,
+} from './types'
+export {
+  WINDO_ACTION_TRIGGERS,
+  WINDO_PLACEMENTS,
+  WINDO_STATUSES,
+} from './types'