beast-devtools 0.0.1

package/devtools/client/highlight.ts

@@ -0,0 +1,210 @@
+/**
+ * A small line-oriented highlighter for BTSX and generated TSRX. It favors
+ * cheap, predictable output over precision: every line is tokenized
+ * independently, except BTSX `module`/`setup`/`style` blocks, whose indented
+ * bodies switch the lexer into TypeScript or CSS mode.
+ */
+
+export type TokenType =
+  | 'text'
+  | 'keyword'
+  | 'string'
+  | 'number'
+  | 'comment'
+  | 'tag'
+  | 'component'
+  | 'selector'
+  | 'attr'
+  | 'directive'
+  | 'interp'
+  | 'punct'
+  | 'type'
+
+export interface Token {
+  type: TokenType
+  value: string
+}
+
+export type Language = 'btsx' | 'tsrx'
+
+const JS_KEYWORDS = new Set([
+  'as', 'async', 'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'default', 'else', 'export',
+  'extends', 'false', 'for', 'from', 'function', 'if', 'import', 'in', 'interface', 'let', 'new', 'null', 'of',
+  'return', 'switch', 'throw', 'true', 'try', 'type', 'typeof', 'undefined', 'var', 'void', 'while',
+])
+
+const BTSX_KEYWORDS = new Set([
+  'case', 'catch', 'component', 'default', 'each', 'else', 'elseif', 'empty', 'fragment', 'if', 'import', 'in',
+  'key', 'module', 'pending', 'props', 'scope', 'setup', 'style', 'switch', 'try',
+])
+
+/** Header words of `each item, i in items key item.id` and `@for (...; index i; key k)`. */
+const EACH_KEYWORDS = new Set(['in', 'key'])
+const FOR_KEYWORDS = new Set(['index', 'key'])
+
+/** BTSX keywords whose bare form opens an indented TypeScript or CSS block. */
+const BLOCK_OPENERS: Record<string, 'ts' | 'css'> = { module: 'ts', setup: 'ts', style: 'css' }
+
+export function highlight(source: string, language: Language): Token[][] {
+  const lines = source.split('\n')
+  if (language === 'tsrx') {
+    return lines.map((line) => merge(lexCode(line, true, /@for\b/.test(line) ? FOR_KEYWORDS : undefined)))
+  }
+
+  let block: { indent: number; mode: 'ts' | 'css' } | null = null
+  return lines.map((line) => {
+    const indent = /^ */.exec(line)![0].length
+    const trimmed = line.trim()
+    if (block !== null && (trimmed === '' || indent > block.indent)) {
+      return merge(block.mode === 'css' ? lexCss(line) : lexCode(line, false))
+    }
+    block = null
+    const opener = BLOCK_OPENERS[trimmed]
+    if (opener !== undefined) block = { indent, mode: opener }
+    return merge(lexBtsxLine(line))
+  })
+}
+
+function lexBtsxLine(line: string): Token[] {
+  const lead = /^ */.exec(line)![0]
+  const body = line.slice(lead.length)
+  const tokens: Token[] = [{ type: 'text', value: lead }]
+  if (body.startsWith('//')) return [...tokens, { type: 'comment', value: body }]
+  if (body.startsWith('~')) return [...tokens, { type: 'punct', value: '~' }, ...lexCode(body.slice(1), true)]
+  if (body.startsWith('|')) return [...tokens, { type: 'punct', value: '|' }, ...lexText(body.slice(1))]
+
+  const word = /^[A-Za-z_$][\w$]*/.exec(body)?.[0]
+  if (word !== undefined && BTSX_KEYWORDS.has(word) && !/^[.#(]/.test(body.slice(word.length))) {
+    const rest = body.slice(word.length)
+    // `component Name` names a component; other keywords are followed by code.
+    if (word === 'component') {
+      return [...tokens, { type: 'keyword', value: word }, ...lexCode(rest, false).map(asComponentName)]
+    }
+    return [...tokens, { type: 'keyword', value: word }, ...lexCode(rest, false, word === 'each' ? EACH_KEYWORDS : undefined)]
+  }
+
+  const selector = /^([A-Za-z][\w.$-]*)?((?:[#.][\w-]+)*)/.exec(body)
+  if (selector === null || selector[0] === '') return [...tokens, ...lexText(body)]
+  const [, tag = '', suffix = ''] = selector
+  const isComponent = /^[A-Z]/.test(tag)
+  if (tag !== '') tokens.push({ type: isComponent ? 'component' : 'tag', value: tag })
+  if (suffix !== '') tokens.push({ type: 'selector', value: suffix })
+
+  let rest = body.slice(selector[0].length)
+  if (rest.startsWith('(')) {
+    const close = matchingParen(rest)
+    tokens.push(...lexCode(rest.slice(0, close + 1), true))
+    rest = rest.slice(close + 1)
+  }
+  return [...tokens, ...lexText(rest)]
+}
+
+function asComponentName(token: Token): Token {
+  return token.type === 'type' ? { type: 'component', value: token.value } : token
+}
+
+/** Literal text with `#{...}` interpolations. */
+function lexText(text: string): Token[] {
+  const tokens: Token[] = []
+  let i = 0
+  while (i < text.length) {
+    const start = text.indexOf('#{', i)
+    if (start === -1) {
+      tokens.push({ type: 'text', value: text.slice(i) })
+      break
+    }
+    if (start > i) tokens.push({ type: 'text', value: text.slice(i, start) })
+    let depth = 0
+    let end = start + 1
+    for (; end < text.length; end++) {
+      if (text[end] === '{') depth++
+      else if (text[end] === '}' && --depth === 0) break
+    }
+    tokens.push({ type: 'interp', value: '#{' }, ...lexCode(text.slice(start + 2, end), false))
+    if (end < text.length) tokens.push({ type: 'interp', value: '}' })
+    i = end + 1
+  }
+  return tokens
+}
+
+type Classifier = (match: string, markup: boolean, keywords: ReadonlySet<string> | undefined) => TokenType | null
+
+/** Ordered lexer rules; a classifier returning null lets later rules try. */
+const CODE_RULES: Array<[RegExp, TokenType | Classifier]> = [
+  [/^\/\/.*/, 'comment'],
+  [/^\/\*.*?(\*\/|$)/, 'comment'],
+  [/^(['"])(?:\\.|(?!\1).)*\1?/, 'string'],
+  [/^`(?:\\.|[^`])*`?/, 'string'],
+  [/^\d[\d_]*(?:\.\d+)?/, 'number'],
+  [/^@(?:if|else|for|switch|case|default|try|pending|catch|empty)\b/, 'directive'],
+  [/^<\/?[A-Za-z][\w.:-]*/, (match, markup) => (!markup ? null : /^<\/?[A-Z]/.test(match) ? 'component' : 'tag')],
+  [/^\/?>/, (_match, markup) => (markup ? 'tag' : 'punct')],
+  [/^[A-Za-z_$][\w$-]*(?==(?!=))/, (match, markup) => (markup || match.includes('-') ? 'attr' : 'text')],
+  [/^[A-Za-z_$][\w$]*/, (match, _markup, keywords) =>
+    JS_KEYWORDS.has(match) || keywords?.has(match) === true ? 'keyword' : /^[A-Z]/.test(match) ? 'type' : 'text'],
+  [/^\s+/, 'text'],
+  [/^[{}()[\];:,.=+\-*/%!?&|<>~^@]/, 'punct'],
+]
+
+/** TypeScript-ish code; `markup` enables JSX-style tag and attribute coloring. */
+function lexCode(code: string, markup: boolean, keywords?: ReadonlySet<string>): Token[] {
+  const tokens: Token[] = []
+  let rest = code
+  outer: while (rest.length > 0) {
+    for (const [pattern, rule] of CODE_RULES) {
+      const match = pattern.exec(rest)?.[0]
+      if (match === undefined || match === '') continue
+      const type = typeof rule === 'function' ? rule(match, markup, keywords) : rule
+      if (type === null) continue
+      tokens.push({ type, value: match })
+      rest = rest.slice(match.length)
+      continue outer
+    }
+    tokens.push({ type: 'text', value: rest[0]! })
+    rest = rest.slice(1)
+  }
+  return tokens
+}
+
+function lexCss(line: string): Token[] {
+  const comment = line.indexOf('/*')
+  if (comment !== -1) return [...lexCss(line.slice(0, comment)), { type: 'comment', value: line.slice(comment) }]
+  const declaration = /^(\s*)([\w-]+)(\s*:\s*)(.*?)(;?\s*)$/.exec(line)
+  if (declaration !== null && !line.trimEnd().endsWith('{')) {
+    const [, lead = '', property = '', colon = '', value = '', end = ''] = declaration
+    return [
+      { type: 'text', value: lead },
+      { type: 'attr', value: property },
+      { type: 'punct', value: colon },
+      { type: 'string', value },
+      { type: 'punct', value: end },
+    ]
+  }
+  return [{ type: 'selector', value: line }]
+}
+
+function matchingParen(text: string): number {
+  let depth = 0
+  let quote: string | null = null
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i]!
+    if (quote !== null) {
+      if (char === '\\') i++
+      else if (char === quote) quote = null
+    } else if (char === '"' || char === "'" || char === '`') quote = char
+    else if (char === '(' || char === '{' || char === '[') depth++
+    else if ((char === ')' || char === '}' || char === ']') && --depth === 0) return i
+  }
+  return text.length - 1
+}
+
+function merge(tokens: Token[]): Token[] {
+  const merged: Token[] = []
+  for (const token of tokens) {
+    if (token.value === '') continue
+    const last = merged.at(-1)
+    if (last !== undefined && last.type === token.type) last.value += token.value
+    else merged.push({ ...token })
+  }
+  return merged
+}

package/devtools/client/mount.ts

@@ -0,0 +1,16 @@
+import { createRoot } from 'octane'
+import BeastDevtools from './BeastDevtools.btsx'
+import './devtools.css'
+
+const HOST_ID = 'beast-devtools'
+
+function mount(): void {
+  if (document.getElementById(HOST_ID) !== null) return
+  const host = document.createElement('div')
+  host.id = HOST_ID
+  document.body.append(host)
+  createRoot(host).render(BeastDevtools, {})
+}
+
+if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', mount, { once: true })
+else mount()

package/devtools/client/runtime.ts

@@ -0,0 +1,168 @@
+/**
+ * External store over Octane's `__OCTANE_DEVTOOLS__` inspection hook.
+ *
+ * The overlay is itself an Octane root, so every overlay render also flushes
+ * and notifies the hook. The store therefore publishes a new snapshot only
+ * when the (overlay-filtered) tree or the selected node's detail actually
+ * changes; an overlay-only flush produces an identical key and stops there.
+ */
+
+interface HookTreeNode {
+  id: number
+  name: string
+  kind: string
+  children: HookTreeNode[]
+}
+
+export interface HookCell {
+  kind: 'state' | 'reducer' | 'ref' | 'memo-or-callback' | 'other'
+  value: unknown
+}
+
+export interface NodeDetail {
+  id: number
+  name: string
+  hooks: HookCell[]
+  context: Array<{ name: string; value: unknown }>
+  effectCount: number
+}
+
+interface OctaneDevtoolsHook {
+  version: number
+  getTree(): HookTreeNode[]
+  inspect(id: number): NodeDetail | null
+  subscribe(listener: () => void): () => void
+}
+
+export interface RuntimeNode {
+  id: number
+  name: string
+  /** Display name: generated control-flow scopes such as `__item$1` become `@item`. */
+  label: string
+  kind: string
+  controlFlow: boolean
+  children: RuntimeNode[]
+}
+
+export interface RuntimeSnapshot {
+  status: 'connecting' | 'unavailable' | 'connected'
+  roots: RuntimeNode[]
+  componentCount: number
+  selectedId: number | null
+  detail: NodeDetail | null
+}
+
+/** The overlay's own root component; it is hidden from the inspected tree. */
+export const OVERLAY_ROOT = 'BeastDevtools'
+
+const listeners = new Set<() => void>()
+let snapshot: RuntimeSnapshot = { status: 'connecting', roots: [], componentCount: 0, selectedId: null, detail: null }
+let treeKey = ''
+let detailKey = ''
+let selectedId: number | null = null
+let frame = 0
+let retry: ReturnType<typeof setTimeout> | undefined
+let disconnect: (() => void) | null = null
+
+function hook(): OctaneDevtoolsHook | undefined {
+  return (globalThis as { __OCTANE_DEVTOOLS__?: OctaneDevtoolsHook }).__OCTANE_DEVTOOLS__
+}
+
+export function subscribeRuntime(listener: () => void): () => void {
+  listeners.add(listener)
+  if (listeners.size === 1) connect(0)
+  return () => {
+    listeners.delete(listener)
+    if (listeners.size > 0) return
+    disconnect?.()
+    disconnect = null
+    clearTimeout(retry)
+    cancelAnimationFrame(frame)
+    frame = 0
+  }
+}
+
+export function getRuntimeSnapshot(): RuntimeSnapshot {
+  return snapshot
+}
+
+export function selectRuntimeNode(id: number | null): void {
+  selectedId = id
+  refresh()
+}
+
+function connect(attempt: number): void {
+  const current = hook()
+  if (current === undefined) {
+    // Octane installs the hook with its first profiled root. Give slow boots a
+    // few seconds before reporting that profiling is off.
+    if (attempt < 10) retry = setTimeout(() => connect(attempt + 1), 300)
+    else publish({ ...snapshot, status: 'unavailable' })
+    return
+  }
+  disconnect = current.subscribe(schedule)
+  refresh()
+}
+
+function schedule(): void {
+  if (frame !== 0) return
+  frame = requestAnimationFrame(() => {
+    frame = 0
+    refresh()
+  })
+}
+
+function refresh(): void {
+  const current = hook()
+  if (current === undefined) return
+
+  const roots = current
+    .getTree()
+    .filter((root) => root.name !== OVERLAY_ROOT)
+    .map(describe)
+  const ids = new Set<number>()
+  let componentCount = 0
+  const visit = (node: RuntimeNode) => {
+    ids.add(node.id)
+    if (!node.controlFlow) componentCount++
+    node.children.forEach(visit)
+  }
+  roots.forEach(visit)
+  if (selectedId !== null && !ids.has(selectedId)) selectedId = null
+
+  const detail = selectedId === null ? null : current.inspect(selectedId)
+  const nextTreeKey = JSON.stringify(roots)
+  const nextDetailKey = `${selectedId}:${safeStringify(detail)}`
+  if (snapshot.status === 'connected' && nextTreeKey === treeKey && nextDetailKey === detailKey) return
+
+  treeKey = nextTreeKey
+  detailKey = nextDetailKey
+  publish({ status: 'connected', roots, componentCount, selectedId, detail })
+}
+
+function publish(next: RuntimeSnapshot): void {
+  snapshot = next
+  for (const listener of listeners) listener()
+}
+
+function describe(node: HookTreeNode): RuntimeNode {
+  const generated = /^__([A-Za-z]+)\$\d+$/.exec(node.name)
+  const controlFlow = node.kind === 'control-flow' || generated !== null
+  return {
+    id: node.id,
+    name: node.name,
+    label: generated === null ? node.name : `@${generated[1]}`,
+    kind: node.kind,
+    controlFlow,
+    children: node.children.map(describe),
+  }
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value, (_key, item) => (typeof item === 'bigint' ? `${item}n` : item)) ?? 'undefined'
+  } catch {
+    // Must stay stable: a changing key would republish on every overlay flush.
+    return '[unserializable]'
+  }
+}

package/devtools/client/util.ts

@@ -0,0 +1,136 @@
+import { DEFAULT_SETTINGS, type AnalyzerSettings } from '../shared/types.ts'
+
+export function cx(...parts: Array<string | false | null | undefined>): string {
+  return parts.filter(Boolean).join(' ')
+}
+
+// ---------------------------------------------------------------------------
+// Value previews for inspected hook and context values
+
+export function isExpandable(value: unknown): boolean {
+  return value !== null && typeof value === 'object' && Object.keys(value).length > 0
+}
+
+/** One-line, length-capped rendering of an inspected value. */
+export function preview(value: unknown, budget = 90): string {
+  const text = previewInner(value, 0)
+  return text.length > budget ? `${text.slice(0, budget - 1)}…` : text
+}
+
+function previewInner(value: unknown, depth: number): string {
+  if (value === undefined) return 'undefined'
+  if (value === null) return 'null'
+  if (typeof value === 'string') return /^\[(Function|Node|Getter|Array|Object|Unavailable)\]$/.test(value) ? value : JSON.stringify(value)
+  if (typeof value !== 'object') return String(value)
+  if (depth >= 2) return Array.isArray(value) ? `Array(${value.length})` : '{…}'
+  if (Array.isArray(value)) return `[${value.map((item) => previewInner(item, depth + 1)).join(', ')}]`
+  const entries = Object.entries(value).map(([key, item]) => `${key}: ${previewInner(item, depth + 1)}`)
+  return entries.length === 0 ? '{}' : `{ ${entries.join(', ')} }`
+}
+
+export function pretty(value: unknown): string {
+  return JSON.stringify(value, (_key, item) => (item === undefined ? '__undefined__' : item), 2)
+    .replaceAll('"__undefined__"', 'undefined')
+}
+
+export function valueTone(value: unknown): string {
+  if (value === null || value === undefined) return 'bdt-v-nil'
+  if (typeof value === 'string') return /^\[\w+\]$/.test(value) ? 'bdt-v-special' : 'bdt-v-string'
+  if (typeof value === 'number' || typeof value === 'bigint') return 'bdt-v-number'
+  if (typeof value === 'boolean') return 'bdt-v-boolean'
+  return 'bdt-v-object'
+}
+
+// ---------------------------------------------------------------------------
+// Preferences, persisted per browser
+
+export type TabId = 'components' | 'inspector' | 'refactor'
+
+export interface Preferences {
+  open: boolean
+  tab: TabId
+  height: number
+  file: string | null
+  showControlFlow: boolean
+  settings: AnalyzerSettings
+}
+
+const STORAGE_KEY = 'beast-devtools:preferences'
+
+export const DEFAULT_PREFERENCES: Preferences = {
+  open: false,
+  tab: 'components',
+  height: 360,
+  file: null,
+  showControlFlow: true,
+  settings: DEFAULT_SETTINGS,
+}
+
+export function loadPreferences(): Preferences {
+  try {
+    const stored = JSON.parse(localStorage.getItem(STORAGE_KEY) ?? '{}') as Partial<Preferences>
+    return {
+      ...DEFAULT_PREFERENCES,
+      ...stored,
+      settings: { ...DEFAULT_SETTINGS, ...stored.settings },
+      height: clampHeight(stored.height ?? DEFAULT_PREFERENCES.height),
+    }
+  } catch {
+    return DEFAULT_PREFERENCES
+  }
+}
+
+export function savePreferences(preferences: Preferences): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(preferences))
+  } catch {
+    // Storage can be unavailable (private mode, blocked site data); preferences are optional.
+  }
+}
+
+export function clampHeight(height: number): number {
+  const max = Math.max(240, (typeof window === 'undefined' ? 900 : window.innerHeight) - 48)
+  return Math.round(Math.min(max, Math.max(200, height)))
+}
+
+/** Drive a vertical resize from a pointer-down on the panel's top edge. */
+export function startResize(event: PointerEvent, height: number, setHeight: (height: number) => void): void {
+  event.preventDefault()
+  const startY = event.clientY
+  const move = (moveEvent: PointerEvent) => setHeight(clampHeight(height + startY - moveEvent.clientY))
+  const stop = () => {
+    window.removeEventListener('pointermove', move)
+    window.removeEventListener('pointerup', stop)
+    document.documentElement.style.removeProperty('cursor')
+  }
+  document.documentElement.style.cursor = 'ns-resize'
+  window.addEventListener('pointermove', move)
+  window.addEventListener('pointerup', stop)
+}
+
+/** Scroll a line into the middle of its scroll container without moving the page. */
+export function scrollToLine(container: HTMLElement | null, line: number | null): void {
+  if (container === null || line === null) return
+  const row = container.querySelector<HTMLElement>(`[data-line="${line}"]`)
+  if (row === null) return
+  const top = row.offsetTop - container.clientHeight / 2 + row.offsetHeight / 2
+  container.scrollTo({ top: Math.max(0, top), behavior: 'smooth' })
+}
+
+/** A scroll request; the nonce lets the same line be requested twice. */
+export interface ScrollTarget {
+  line: number
+  nonce: number
+}
+
+let scrollNonce = 0
+
+export function scrollTarget(line: number): ScrollTarget {
+  return { line, nonce: ++scrollNonce }
+}
+
+/** The last applied refactor, kept by the shell so Undo survives tab switches. */
+export interface RecentRefactor {
+  undoId: string
+  summary: string
+}

package/devtools/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@beastjs/devtools",
+  "version": "0.1.0",
+  "description": "In-page devtools for Beast (BTSX) and Octane apps: live component state, BTSX → TSRX inspection, and automatic component extraction for deeply nested templates.",
+  "license": "ISC",
+  "author": "phtn",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beastjs/devtools.git",
+    "directory": "devtools"
+  },
+  "homepage": "https://github.com/beastjs/devtools/tree/main/devtools#readme",
+  "bugs": {
+    "url": "https://github.com/beastjs/devtools/issues"
+  },
+  "keywords": [
+    "beast",
+    "btsx",
+    "tsrx",
+    "octane",
+    "devtools",
+    "vite",
+    "vite-plugin",
+    "refactor"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/vite.js",
+  "types": "./dist/vite.d.ts",
+  "files": [
+    "dist",
+    "client",
+    "shared",
+    "!**/*.test.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "prepublishOnly": "bun run build && bun test"
+  },
+  "peerDependencies": {
+    "beast-tsrx": "^0.4.3",
+    "octane": "^0.4.3",
+    "vite": "^8.0.16"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "beast-tsrx": "0.4.3",
+    "octane": "0.4.3",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}