From 551d7ec0295de9783a59b30329692f1832f1417c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 16 Sep 2026 16:13:53 +0000
Subject: [PATCH 1/2] feat(widgets): add protobuf decoder widget

Paste a protobuf payload as base64 or hex and read it, with or without the
.proto that produced it. Everything runs in the browser.

Without a definition, the payload is decoded straight from the wire
format: field numbers, wire types, nested messages, and a reading of every
value. The wire format does not carry names or declared types, so where
the bytes are genuinely ambiguous the widget lists the other readings
instead of picking one silently: a varint that could be a bool or a zigzag
sint64, a length-delimited field that parses as a nested message and is
also printable text, bytes that could be a packed repeated field.

With a definition, protobufjs parses the .proto text at runtime (no
codegen, no protoc) and the decoded message is shown as a named tree. The
schema-less reading is kept alongside and the two are compared, because
protobufjs drops in silence both the fields a definition does not declare
and the declared fields that arrive as the wrong wire type. Either one is
reported: the first as fields that were dropped, the second as the sign
that the payload is probably a different message type.

Other conveniences: the encoding is detected rather than asked for (hex
wins a tie), hex dumps keep their separators and 0x prefixes, base64url
and missing padding are accepted, and a 5-byte gRPC length prefix is
recognized and skipped. Payloads are capped at 100,000 characters and 64
KB of bytes, definitions at 50,000 characters.

protobufjs is added as a dependency; it lands in the widget's own lazy
chunk (132 KB, 38 KB gzipped), so nothing changes for a dashboard that
never opens this widget.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K2aiBGNxfoFs9oBpSVBTsE
---
 README.md                                     |   6 +-
 package-lock.json                             |  19 ++
 package.json                                  |   1 +
 .../ProtobufDecoderWidget.test.tsx            | 165 +++++++++
 .../ProtobufDecoderWidget.tsx                 | 287 ++++++++++++++++
 src/widgets/protobuf-decoder/definition.ts    |  29 ++
 .../protobuf-decoder/payloadBytes.test.ts     |  78 +++++
 src/widgets/protobuf-decoder/payloadBytes.ts  | 137 ++++++++
 .../protobuf-decoder/protoSchema.test.ts      | 155 +++++++++
 src/widgets/protobuf-decoder/protoSchema.ts   | 219 ++++++++++++
 .../protobuf-decoder/wireFormat.test.ts       | 167 +++++++++
 src/widgets/protobuf-decoder/wireFormat.ts    | 321 ++++++++++++++++++
 src/widgets/registry.ts                       |   2 +
 13 files changed, 1583 insertions(+), 3 deletions(-)
 create mode 100644 src/widgets/protobuf-decoder/ProtobufDecoderWidget.test.tsx
 create mode 100644 src/widgets/protobuf-decoder/ProtobufDecoderWidget.tsx
 create mode 100644 src/widgets/protobuf-decoder/definition.ts
 create mode 100644 src/widgets/protobuf-decoder/payloadBytes.test.ts
 create mode 100644 src/widgets/protobuf-decoder/payloadBytes.ts
 create mode 100644 src/widgets/protobuf-decoder/protoSchema.test.ts
 create mode 100644 src/widgets/protobuf-decoder/protoSchema.ts
 create mode 100644 src/widgets/protobuf-decoder/wireFormat.test.ts
 create mode 100644 src/widgets/protobuf-decoder/wireFormat.ts

diff --git a/README.md b/README.md
index 6bfa5eb..a38fdb5 100644
--- a/README.md
+++ b/README.md
@@ -57,14 +57,14 @@ always asks before it touches your local dashboard.
 
 ## Widgets
 
-33 tools across 10 categories, and growing.
+36 tools across 10 categories, and growing.
 
 | Category   | Widgets                                                                                                   |
 | ---------- | --------------------------------------------------------------------------------------------------------- |
 | Generators | UUID Generator                                                                                            |
 | Formatting | Cron Expression, JSON Formatter, Timestamp Converter, XML Formatter, YAML ↔ JSON Converter                |
-| Encoding   | Base64, JWT Encoder, LZ-String, URL Encoder                                                               |
-| Security   | Certificate Viewer, Hash Generator, JWK Viewer, Password Generator                                        |
+| Encoding   | Base64, JWT Encoder, LZ-String, Protobuf Decoder, URL Encoder                                             |
+| Security   | Certificate Viewer, Hash Generator, JWK Viewer, Password Generator, Unix Permissions                      |
 | Text       | Content Type Detector, Emoji Picker, Log Viewer, Notes, Regex Tester, Text Case Converter, Text Diff      |
 | Math       | Expression Evaluator, Number Base Converter, Percentage Calculator, Statistics Calculator, Unit Converter |
 | AI / LLM   | Invisible Character Cleaner, Token Counter                                                                |
diff --git a/package-lock.json b/package-lock.json
index a205408..db8a349 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -28,6 +28,7 @@
         "lucide-react": "^1.30.0",
         "lz-string": "^1.5.0",
         "nanoid": "^6.0.1",
+        "protobufjs": "^8.8.0",
         "qrcode.react": "^4.2.0",
         "react": "^19.2.8",
         "react-dom": "^19.2.8",
@@ -7189,6 +7190,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/long": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz",
+      "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==",
+      "license": "Apache-2.0"
+    },
     "node_modules/loose-envify": {
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
@@ -7701,6 +7708,18 @@
       "integrity": "sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ==",
       "license": "MIT"
     },
+    "node_modules/protobufjs": {
+      "version": "8.8.0",
+      "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-8.8.0.tgz",
+      "integrity": "sha512-N3xhQ5yyBx3vQq4gubBfASzYhJGNzeDbjqBpu61g7UVylsN/qyffU96TKWD3GbbLOKF82VGNRNvv1+BFgE31Eg==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "long": "^5.3.2"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/punycode": {
       "version": "2.3.1",
       "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
diff --git a/package.json b/package.json
index 3caf393..3a2868b 100644
--- a/package.json
+++ b/package.json
@@ -53,6 +53,7 @@
     "lucide-react": "^1.30.0",
     "lz-string": "^1.5.0",
     "nanoid": "^6.0.1",
+    "protobufjs": "^8.8.0",
     "qrcode.react": "^4.2.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
diff --git a/src/widgets/protobuf-decoder/ProtobufDecoderWidget.test.tsx b/src/widgets/protobuf-decoder/ProtobufDecoderWidget.test.tsx
new file mode 100644
index 0000000..50b58dd
--- /dev/null
+++ b/src/widgets/protobuf-decoder/ProtobufDecoderWidget.test.tsx
@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'vitest'
+import { render, screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { setCodeMirrorValue } from '@/test/codemirror'
+import ProtobufDecoderWidget from './ProtobufDecoderWidget'
+
+/** The sample payload the widget opens on: Person { id: 150, name:
+ * "testing", tags: ["a", "b"], home: { city: "Paris" } }. */
+const SAMPLE_PAYLOAD = 'CJYBEgd0ZXN0aW5nGgFhGgFiIgcKBVBhcmlz'
+
+function payloadBox() {
+  return screen.getByPlaceholderText(/paste a base64 or hex protobuf payload/i)
+}
+
+async function setPayload(user: ReturnType<typeof userEvent.setup>, text: string) {
+  await user.clear(payloadBox())
+  if (text) await user.paste(text)
+}
+
+describe('ProtobufDecoderWidget', () => {
+  it('decodes the sample payload without a schema, field by field', () => {
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+
+    const rows = screen.getAllByRole('listitem')
+    expect(within(rows[0]).getByText('1')).toBeInTheDocument()
+    expect(within(rows[0]).getByText('150')).toBeInTheDocument()
+    expect(within(rows[0]).getByText('varint')).toBeInTheDocument()
+    expect(screen.getByText('"testing"')).toBeInTheDocument()
+    expect(screen.getByText('"Paris"')).toBeInTheDocument()
+  })
+
+  it('says what the encoding and size turned out to be', () => {
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+    expect(screen.getByText(/base64, 27 bytes/i)).toBeInTheDocument()
+  })
+
+  it('reads the same payload pasted as hex', async () => {
+    const user = userEvent.setup()
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+
+    await setPayload(user, '08 96 01 12 07 74 65 73 74 69 6e 67')
+
+    expect(screen.getByText(/hex, 12 bytes/i)).toBeInTheDocument()
+    expect(screen.getByText('"testing"')).toBeInTheDocument()
+  })
+
+  it('strips a gRPC frame and says it did', async () => {
+    const user = userEvent.setup()
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+
+    await setPayload(user, '0000000003089601')
+
+    expect(screen.getByText(/gRPC frame detected/i)).toBeInTheDocument()
+    expect(screen.getByText('150')).toBeInTheDocument()
+  })
+
+  it('offers the other readings of an ambiguous value', async () => {
+    const user = userEvent.setup()
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+
+    // Field 1, varint 1: as likely a bool as a number.
+    await setPayload(user, '0801')
+
+    expect(screen.getByText(/or bool true/i)).toBeInTheDocument()
+  })
+
+  it('explains what a schema-less decode cannot know', () => {
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+    expect(screen.getByText(/names and declared types are not in the bytes/i)).toBeInTheDocument()
+  })
+
+  it('names the fields once the .proto is supplied', async () => {
+    const user = userEvent.setup()
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+
+    await user.click(screen.getByRole('button', { name: /with \.proto/i }))
+
+    expect(screen.getByRole('combobox', { name: /message/i })).toHaveValue('Person')
+    expect(screen.getByText('name')).toBeInTheDocument()
+    expect(screen.getByText('"testing"')).toBeInTheDocument()
+    expect(screen.getByText('city')).toBeInTheDocument()
+  })
+
+  it('lets the message type be switched to another one in the definition', async () => {
+    const user = userEvent.setup()
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+
+    await user.click(screen.getByRole('button', { name: /with \.proto/i }))
+    await user.selectOptions(screen.getByRole('combobox', { name: /message/i }), 'Address')
+
+    // Person's payload is not an Address. protobufjs decodes it to an empty
+    // object without complaining, so the widget is what has to say why.
+    expect(screen.getByText(/Field 1 arrived as varint but is declared string city/i)).toBeInTheDocument()
+    expect(screen.getByText(/Fields 2, 3, 4 on the wire/i)).toBeInTheDocument()
+  })
+
+  it('reports a syntax error in the definition with its line', async () => {
+    const user = userEvent.setup()
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+
+    await user.click(screen.getByRole('button', { name: /with \.proto/i }))
+    setCodeMirrorValue(
+      screen.getByRole('textbox', { name: 'Proto definition' }),
+      'syntax = "proto3";\nmessage B { int32 id = ; }',
+    )
+
+    expect(screen.getByText(/line 2/i)).toBeInTheDocument()
+  })
+
+  it('warns when the payload carries fields the definition never declared', async () => {
+    const user = userEvent.setup()
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+
+    await user.click(screen.getByRole('button', { name: /with \.proto/i }))
+    // Field 1 (declared) plus field 9 (not in Person).
+    await setPayload(user, '0896014a0568656c6c6f')
+
+    expect(screen.getByText(/Field 9 on the wire is not in this definition/i)).toBeInTheDocument()
+  })
+
+  it('reports an unusable payload instead of decoding noise', async () => {
+    const user = userEvent.setup()
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+
+    await setPayload(user, 'not a payload!!')
+
+    expect(screen.getByText(/neither valid hex nor valid base64/i)).toBeInTheDocument()
+  })
+
+  it('keeps what it read before a truncated payload gave out', async () => {
+    const user = userEvent.setup()
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+
+    await setPayload(user, '0896011209746573')
+
+    expect(screen.getByText('150')).toBeInTheDocument()
+    expect(screen.getByText(/past the end of the payload/i)).toBeInTheDocument()
+    expect(screen.getByText(/everything above was read before that point/i)).toBeInTheDocument()
+  })
+
+  it('keeps payload, mode and definition across a remount of the same instance', async () => {
+    const user = userEvent.setup()
+    const { unmount } = render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+
+    await user.click(screen.getByRole('button', { name: /with \.proto/i }))
+    await setPayload(user, '089601')
+    unmount()
+
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+    expect(screen.getByRole('button', { name: /with \.proto/i })).toHaveAttribute('aria-pressed', 'true')
+    expect(payloadBox()).toHaveValue('089601')
+    expect(screen.getByText('id')).toBeInTheDocument()
+  })
+
+  it('still decodes the sample payload after it has been re-pasted', async () => {
+    const user = userEvent.setup()
+    render(<ProtobufDecoderWidget instanceId="test" mode="grid" />)
+
+    await setPayload(user, '')
+    expect(screen.getByText(/paste a base64 or hex payload/i)).toBeInTheDocument()
+
+    await user.paste(SAMPLE_PAYLOAD)
+    expect(screen.getByText('"testing"')).toBeInTheDocument()
+  })
+})
diff --git a/src/widgets/protobuf-decoder/ProtobufDecoderWidget.tsx b/src/widgets/protobuf-decoder/ProtobufDecoderWidget.tsx
new file mode 100644
index 0000000..0ddd7be
--- /dev/null
+++ b/src/widgets/protobuf-decoder/ProtobufDecoderWidget.tsx
@@ -0,0 +1,287 @@
+import { useMemo } from 'react'
+import { CodeEditor } from '@/components/CodeEditor'
+import { CopyButton } from '@/components/CopyButton'
+import { DataTree } from '@/components/data-tree/DataTree'
+import { buildJsonTree } from '@/components/data-tree/treeModel'
+import { ErrorMessage } from '@/components/ErrorMessage'
+import { SegmentedControl } from '@/components/SegmentedControl'
+import { Textarea } from '@/components/ui/textarea'
+import { cn } from '@/lib/utils'
+import { useWidgetDirty } from '@/widgets/useWidgetDirty'
+import { useWidgetState } from '@/widgets/useWidgetState'
+import type { WidgetProps } from '@/widgets/types'
+import { decodePayload, toHex, type PayloadEncoding } from './payloadBytes'
+import { decodeWithSchema, parseSchema } from './protoSchema'
+import { decodeWireFormat, formatFields, WIRE_TYPE_NAMES, type WireField } from './wireFormat'
+
+type Mode = 'raw' | 'schema'
+
+/** A Person message: an id, a name, two repeated tags, and a nested
+ * address. Enough shape to show what a schema-less decode can and cannot
+ * recover, which is the point of the widget. */
+const SAMPLE_PAYLOAD = 'CJYBEgd0ZXN0aW5nGgFhGgFiIgcKBVBhcmlz'
+
+const SAMPLE_SCHEMA = `syntax = "proto3";
+
+message Person {
+  int32 id = 1;
+  string name = 2;
+  repeated string tags = 3;
+  Address home = 4;
+}
+
+message Address {
+  string city = 1;
+}`
+
+const SELECT_CLASS =
+  'h-6 min-w-0 rounded-md border border-input bg-transparent px-1 text-[11px] outline-none transition-colors focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring/50 dark:bg-input/30'
+
+const ENCODING_OPTIONS: { label: string; value: PayloadEncoding }[] = [
+  { label: 'Auto', value: 'auto' },
+  { label: 'Base64', value: 'base64' },
+  { label: 'Hex', value: 'hex' },
+]
+
+export default function ProtobufDecoderWidget({ instanceId }: WidgetProps) {
+  const [payload, setPayload] = useWidgetState(instanceId, 'payload', SAMPLE_PAYLOAD)
+  const [encoding, setEncoding] = useWidgetState<PayloadEncoding>(instanceId, 'encoding', 'auto')
+  const [mode, setMode] = useWidgetState<Mode>(instanceId, 'mode', 'raw')
+  const [schema, setSchema] = useWidgetState(instanceId, 'schema', SAMPLE_SCHEMA)
+  const [messageName, setMessageName] = useWidgetState(instanceId, 'messageName', '')
+  useWidgetDirty(instanceId, payload !== SAMPLE_PAYLOAD || schema !== SAMPLE_SCHEMA || mode !== 'raw')
+
+  const decodedPayload = useMemo(() => decodePayload(payload, encoding), [payload, encoding])
+  const bytes = 'error' in decodedPayload ? null : decodedPayload.bytes
+
+  const wire = useMemo(() => (bytes ? decodeWireFormat(bytes) : null), [bytes])
+  const parsedSchema = useMemo(() => (mode === 'schema' ? parseSchema(schema) : null), [mode, schema])
+
+  // Fall back to the first message the definition declares until one is
+  // picked, so a freshly pasted .proto decodes without another click.
+  const availableNames = parsedSchema?.ok ? parsedSchema.names : []
+  const selectedName = availableNames.includes(messageName) ? messageName : (availableNames[0] ?? '')
+
+  const schemaDecode = useMemo(() => {
+    if (mode !== 'schema' || !bytes || !parsedSchema?.ok || !selectedName) return null
+    return decodeWithSchema(parsedSchema.root, selectedName, bytes, wire?.fields ?? [])
+  }, [mode, bytes, parsedSchema, selectedName, wire])
+
+  const copyText = useMemo(() => {
+    if (mode === 'schema' && schemaDecode?.ok) return JSON.stringify(schemaDecode.value, null, 2)
+    return wire ? formatFields(wire.fields) : ''
+  }, [mode, schemaDecode, wire])
+
+  return (
+    <div className="flex h-full flex-col gap-2 text-xs">
+      <Textarea
+        value={payload}
+        onChange={(event) => setPayload(event.target.value)}
+        placeholder="Paste a base64 or hex protobuf payload…"
+        spellCheck={false}
+        className="h-14 w-full shrink-0 resize-none p-2 font-mono text-xs"
+      />
+
+      <div className="flex flex-wrap items-center gap-1.5">
+        <SegmentedControl value={encoding} onChange={setEncoding} options={ENCODING_OPTIONS} />
+        <SegmentedControl<Mode>
+          value={mode}
+          onChange={setMode}
+          options={[
+            { label: 'No schema', value: 'raw' },
+            { label: 'With .proto', value: 'schema' },
+          ]}
+        />
+        {bytes && (
+          <span className="ml-auto shrink-0 text-muted-foreground">
+            {'error' in decodedPayload ? null : decodedPayload.encoding}, {bytes.length.toLocaleString('en-US')} bytes
+          </span>
+        )}
+      </div>
+
+      {'error' in decodedPayload ? (
+        <div className="min-h-0 flex-1 rounded-lg border border-border bg-background p-2 dark:bg-muted/40">
+          <ErrorMessage>{decodedPayload.error}</ErrorMessage>
+        </div>
+      ) : (
+        <>
+          {decodedPayload.grpcFrame && (
+            <p className="text-muted-foreground">
+              gRPC frame detected: skipped the 5-byte {decodedPayload.grpcFrame.compressed ? 'compressed' : 'length'}{' '}
+              prefix.
+              {decodedPayload.grpcFrame.compressed && ' The body is compressed, so this decode will not make sense.'}
+            </p>
+          )}
+
+          {mode === 'schema' && (
+            <>
+              <CodeEditor
+                value={schema}
+                onChange={setSchema}
+                language="plaintext"
+                placeholder="Paste the .proto definition…"
+                aria-label="Proto definition"
+                className="min-h-16 flex-1 shrink-0"
+              />
+              <div className="flex items-center gap-1.5">
+                <label htmlFor={`${instanceId}-message`} className="shrink-0 text-muted-foreground">
+                  Message
+                </label>
+                <select
+                  id={`${instanceId}-message`}
+                  value={selectedName}
+                  onChange={(event) => setMessageName(event.target.value)}
+                  disabled={availableNames.length === 0}
+                  className={cn(SELECT_CLASS, 'flex-1')}
+                >
+                  {availableNames.length === 0 ? (
+                    <option value="">No message types</option>
+                  ) : (
+                    availableNames.map((name) => (
+                      <option key={name} value={name}>
+                        {name}
+                      </option>
+                    ))
+                  )}
+                </select>
+              </div>
+            </>
+          )}
+
+          <div className="flex items-center gap-2">
+            <span className="text-muted-foreground">
+              {mode === 'schema' ? 'Decoded with the definition' : 'Structure recovered from the bytes'}
+            </span>
+            <CopyButton value={copyText} className="ml-auto" />
+          </div>
+
+          <div className="min-h-0 flex-1 overflow-auto rounded-lg border border-border bg-background p-2 dark:bg-muted/40">
+            {mode === 'schema' ? (
+              <SchemaPane parsedSchema={parsedSchema} decode={schemaDecode} />
+            ) : (
+              <RawPane wire={wire} />
+            )}
+          </div>
+        </>
+      )}
+    </div>
+  )
+}
+
+function RawPane({ wire }: { wire: ReturnType<typeof decodeWireFormat> | null }) {
+  if (!wire) return null
+  return (
+    <div className="flex flex-col gap-2">
+      {wire.fields.length === 0 && wire.ok && <p className="text-muted-foreground">The payload holds no fields.</p>}
+      {wire.fields.length > 0 && <FieldRows fields={wire.fields} depth={0} />}
+      {!wire.ok && (
+        <div className="flex flex-col gap-1">
+          <ErrorMessage>
+            {wire.reason} (byte {wire.offset})
+          </ErrorMessage>
+          {wire.fields.length > 0 && (
+            <p className="text-muted-foreground">Everything above was read before that point.</p>
+          )}
+          <p className="text-muted-foreground">
+            A payload that fails here is usually not protobuf, is truncated, or still carries a transport header.
+          </p>
+        </div>
+      )}
+      <p className="border-t border-border pt-2 text-muted-foreground">
+        Without the .proto, names and declared types are not in the bytes: a varint could be an int32, a bool or an
+        enum, and the readings below each value are all the payload can tell you.
+      </p>
+    </div>
+  )
+}
+
+function FieldRows({ fields, depth }: { fields: WireField[]; depth: number }) {
+  return (
+    <ul className={cn('flex flex-col gap-0.5', depth > 0 && 'border-l border-border pl-2')}>
+      {fields.map((field, index) => (
+        <li key={`${field.offset}-${index}`} className="flex flex-col gap-0.5">
+          <div className="flex items-baseline gap-2 rounded px-1 py-0.5 hover:bg-accent">
+            <span className="shrink-0 font-mono font-medium tabular-nums">{field.fieldNumber}</span>
+            <span className="shrink-0 rounded bg-muted px-1.5 py-0.5 text-[10px] text-muted-foreground">
+              {WIRE_TYPE_NAMES[field.wireType]}
+            </span>
+            <span className="min-w-0 flex-1 truncate font-mono" title={primaryValue(field)}>
+              {primaryValue(field)}
+            </span>
+          </div>
+          {field.alternatives.length > 0 && (
+            <p className="pl-1 text-[11px] text-muted-foreground">or {field.alternatives.join(' · ')}</p>
+          )}
+          {field.value.kind === 'message' && <FieldRows fields={field.value.fields} depth={depth + 1} />}
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+function primaryValue(field: WireField): string {
+  const { value } = field
+  switch (value.kind) {
+    case 'varint':
+      return String(value.value)
+    case 'fixed64':
+      return String(value.value)
+    case 'fixed32':
+      return String(value.value)
+    case 'string':
+      return JSON.stringify(value.text)
+    case 'bytes':
+      return value.bytes.length === 0 ? '(empty)' : toHex(value.bytes)
+    case 'message':
+      return `{ ${value.fields.length} field${value.fields.length === 1 ? '' : 's'} }`
+  }
+}
+
+function SchemaPane({
+  parsedSchema,
+  decode,
+}: {
+  parsedSchema: ReturnType<typeof parseSchema> | null
+  decode: ReturnType<typeof decodeWithSchema> | null
+}) {
+  if (parsedSchema && !parsedSchema.ok) {
+    return (
+      <ErrorMessage>
+        {parsedSchema.line ? `Line ${parsedSchema.line}: ` : ''}
+        {parsedSchema.reason}
+      </ErrorMessage>
+    )
+  }
+  if (!decode) return <p className="text-muted-foreground">Paste a .proto definition to name these fields.</p>
+  if (!decode.ok) return <ErrorMessage>{decode.reason}</ErrorMessage>
+
+  return (
+    <div className="flex flex-col gap-2">
+      {decode.comparison.unknownFieldNumbers.length > 0 && (
+        <p className="rounded-md bg-destructive/10 px-2 py-1 text-destructive">
+          Field{decode.comparison.unknownFieldNumbers.length === 1 ? '' : 's'}{' '}
+          {decode.comparison.unknownFieldNumbers.join(', ')} on the wire
+          {decode.comparison.unknownFieldNumbers.length === 1 ? ' is' : ' are'} not in this definition, and{' '}
+          {decode.comparison.unknownFieldNumbers.length === 1 ? 'was' : 'were'} dropped. Switch to No schema to see{' '}
+          {decode.comparison.unknownFieldNumbers.length === 1 ? 'it' : 'them'}.
+        </p>
+      )}
+      {/* A declared field arriving as the wrong wire type is the clearest
+       * sign the payload is a different message: protobufjs skips it in
+       * silence, leaving a decode that looks clean and says nothing. */}
+      {decode.comparison.mismatches.map((mismatch) => (
+        <p key={mismatch.fieldNumber} className="rounded-md bg-destructive/10 px-2 py-1 text-destructive">
+          Field {mismatch.fieldNumber} arrived as {WIRE_TYPE_NAMES[mismatch.wireType]} but is declared{' '}
+          {mismatch.declared}, so it was skipped. This payload is probably a different message type.
+        </p>
+      ))}
+      <DataTree
+        root={buildJsonTree(decode.value)}
+        label="Decoded message"
+        toolbar={false}
+        statusBar={false}
+        scroll={false}
+      />
+    </div>
+  )
+}
diff --git a/src/widgets/protobuf-decoder/definition.ts b/src/widgets/protobuf-decoder/definition.ts
new file mode 100644
index 0000000..e6881f3
--- /dev/null
+++ b/src/widgets/protobuf-decoder/definition.ts
@@ -0,0 +1,29 @@
+import { lazy } from 'react'
+import { Binary } from 'lucide-react'
+import type { WidgetDefinition } from '@/widgets/types'
+
+export const protobufDecoderDefinition: WidgetDefinition = {
+  id: 'protobuf-decoder',
+  name: 'Protobuf Decoder',
+  description: 'Decode a protobuf payload from base64 or hex, with its .proto definition or without one',
+  category: 'encoding',
+  icon: Binary,
+  defaultSize: { w: 4, h: 5 },
+  minSize: { w: 3, h: 4 },
+  component: lazy(() => import('./ProtobufDecoderWidget')),
+  keywords: [
+    'protobuf',
+    'proto',
+    'protocol buffers',
+    'grpc',
+    'wire format',
+    'varint',
+    'decode',
+    'binary',
+    'base64',
+    'hex',
+    'serialization',
+    'message',
+    'schema',
+  ],
+}
diff --git a/src/widgets/protobuf-decoder/payloadBytes.test.ts b/src/widgets/protobuf-decoder/payloadBytes.test.ts
new file mode 100644
index 0000000..544b4ce
--- /dev/null
+++ b/src/widgets/protobuf-decoder/payloadBytes.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest'
+import { decodePayload, MAX_INPUT_LENGTH, MAX_PAYLOAD_BYTES, toHex } from './payloadBytes'
+
+function bytesOf(result: ReturnType<typeof decodePayload>): number[] {
+  if ('error' in result) throw new Error(result.error)
+  return [...result.bytes]
+}
+
+describe('decodePayload', () => {
+  it('reads hex, with or without the noise a dump brings along', () => {
+    expect(bytesOf(decodePayload('089601'))).toEqual([0x08, 0x96, 0x01])
+    expect(bytesOf(decodePayload('08 96 01'))).toEqual([0x08, 0x96, 0x01])
+    expect(bytesOf(decodePayload('0x08, 0x96, 0x01'))).toEqual([0x08, 0x96, 0x01])
+    expect(bytesOf(decodePayload('08\n96\n01'))).toEqual([0x08, 0x96, 0x01])
+  })
+
+  it('reads base64, including base64url and missing padding', () => {
+    expect(bytesOf(decodePayload('CJYB'))).toEqual([0x08, 0x96, 0x01])
+    expect(bytesOf(decodePayload('CJYBEgd0ZXN0aW5n')).slice(0, 3)).toEqual([0x08, 0x96, 0x01])
+    // "+/" against "-_", and no trailing "=".
+    expect(bytesOf(decodePayload('-_8'))).toEqual(bytesOf(decodePayload('+/8=')))
+  })
+
+  it('prefers hex when the text is valid as both', () => {
+    const result = decodePayload('089601')
+    expect('error' in result ? null : result.encoding).toBe('hex')
+  })
+
+  it('honours an explicit encoding over the guess', () => {
+    const asBase64 = decodePayload('089601', 'base64')
+    expect('error' in asBase64 ? null : asBase64.encoding).toBe('base64')
+    expect(bytesOf(asBase64)).toEqual([0xd3, 0xcf, 0x7a, 0xd3])
+  })
+
+  it('strips a gRPC length prefix and says it did', () => {
+    // 00 (uncompressed) + length 3 + the payload itself.
+    const result = decodePayload('0000000003089601')
+    if ('error' in result) throw new Error(result.error)
+    expect([...result.bytes]).toEqual([0x08, 0x96, 0x01])
+    expect(result.grpcFrame).toEqual({ compressed: false, length: 3 })
+  })
+
+  it('leaves bytes alone when the length prefix does not match', () => {
+    const result = decodePayload('0000000099089601')
+    if ('error' in result) throw new Error(result.error)
+    expect(result.bytes.length).toBe(8)
+    expect(result.grpcFrame).toBeUndefined()
+  })
+
+  it('reports what is wrong instead of throwing', () => {
+    expect(decodePayload('')).toEqual({ error: 'Paste a base64 or hex payload.' })
+    expect(decodePayload('08960', 'hex')).toEqual({ error: 'Hex payload has an odd number of digits.' })
+    expect(decodePayload('zz zz', 'hex')).toEqual({ error: 'Payload contains characters that are not hex digits.' })
+    expect(decodePayload('not valid!!')).toEqual({ error: 'Payload is neither valid hex nor valid base64.' })
+  })
+
+  it('refuses input past the limits', () => {
+    const tooLong = 'a'.repeat(MAX_INPUT_LENGTH + 1)
+    expect(decodePayload(tooLong)).toEqual({ error: expect.stringContaining('the limit is 100,000') })
+
+    // Base64 packs 3 bytes into 4 characters, so this clears the character
+    // limit and still blows past the byte one. It deliberately uses
+    // characters outside the hex alphabet, or the guess would read it as a
+    // hex dump (half the bytes) instead.
+    const tooManyBytes = 'Zm9v'.repeat(22_500)
+    expect(tooManyBytes.length).toBeLessThan(MAX_INPUT_LENGTH)
+    expect(decodePayload(tooManyBytes)).toEqual({
+      error: expect.stringContaining(`the limit is ${MAX_PAYLOAD_BYTES.toLocaleString('en-US')}`),
+    })
+  })
+})
+
+describe('toHex', () => {
+  it('spaces bytes out and truncates long runs', () => {
+    expect(toHex(new Uint8Array([0x08, 0x96, 0x01]))).toBe('08 96 01')
+    expect(toHex(new Uint8Array(40), 4)).toBe('00 00 00 00 … (40 bytes)')
+  })
+})
diff --git a/src/widgets/protobuf-decoder/payloadBytes.ts b/src/widgets/protobuf-decoder/payloadBytes.ts
new file mode 100644
index 0000000..2c2c6d4
--- /dev/null
+++ b/src/widgets/protobuf-decoder/payloadBytes.ts
@@ -0,0 +1,137 @@
+/** Turns whatever was pasted into the bytes a protobuf decoder can read.
+ *
+ * Payloads arrive from all over: a base64 string out of a JSON log, hex out
+ * of a packet capture or `xxd`, a gRPC frame copied from devtools. The
+ * shapes differ but the intent never does, so the encoding is detected
+ * rather than asked for, and the widget reports what it decided. */
+
+export type PayloadEncoding = 'auto' | 'base64' | 'hex'
+
+export interface DecodedPayload {
+  bytes: Uint8Array
+  /** What the text actually turned out to be. */
+  encoding: 'base64' | 'hex'
+  /** Set when a 5-byte gRPC length prefix was found and skipped. */
+  grpcFrame?: { compressed: boolean; length: number }
+}
+
+export interface PayloadError {
+  error: string
+}
+
+/** Characters that carry no information in either encoding: whitespace from
+ * wrapped lines, `0x` prefixes and separators from hex dumps, quotes and
+ * commas from a pasted code literal. */
+const NOISE = /[\s,"'`]|0x/gi
+
+/** Both limits are about keeping a paste from stalling the tab rather than
+ * about protobuf itself: the decode is linear, but every field becomes a
+ * rendered row. */
+export const MAX_INPUT_LENGTH = 100_000
+export const MAX_PAYLOAD_BYTES = 64 * 1024
+
+function isHexadecimal(text: string): boolean {
+  return text.length % 2 === 0 && text.length > 0 && /^[0-9a-f]+$/i.test(text)
+}
+
+function isBase64(text: string): boolean {
+  return text.length > 0 && /^[A-Za-z0-9+/\-_]+={0,2}$/.test(text)
+}
+
+function fromHex(text: string): Uint8Array {
+  const bytes = new Uint8Array(text.length / 2)
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(text.slice(index * 2, index * 2 + 2), 16)
+  }
+  return bytes
+}
+
+function fromBase64(text: string): Uint8Array | null {
+  // base64url is the same alphabet with two characters swapped, and pasted
+  // values are often missing their padding.
+  const normalized = text.replace(/-/g, '+').replace(/_/g, '/')
+  const padded = normalized.padEnd(normalized.length + ((4 - (normalized.length % 4)) % 4), '=')
+  try {
+    const binary = atob(padded)
+    const bytes = new Uint8Array(binary.length)
+    for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index)
+    return bytes
+  } catch {
+    return null
+  }
+}
+
+/** A gRPC message on the wire is a 1-byte compression flag, a 4-byte
+ * big-endian length, then the protobuf itself. Copying one out of devtools
+ * brings the frame along, and decoding it as protobuf yields nonsense
+ * (field 0), so it is recognized and stripped. */
+function readGrpcFrame(bytes: Uint8Array): { body: Uint8Array; compressed: boolean; length: number } | null {
+  if (bytes.length < 5) return null
+  const flag = bytes[0]
+  if (flag !== 0 && flag !== 1) return null
+  const length = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(1, false)
+  if (length !== bytes.length - 5) return null
+  return { body: bytes.subarray(5), compressed: flag === 1, length }
+}
+
+/** Decodes pasted text into bytes. Returns `{ error }` rather than throwing,
+ * since every failure here is something to show the user: a stray
+ * character, a truncated payload, an input past the size limit. */
+export function decodePayload(text: string, encoding: PayloadEncoding = 'auto'): DecodedPayload | PayloadError {
+  if (text.length > MAX_INPUT_LENGTH) {
+    return {
+      error: `Payload is ${text.length.toLocaleString('en-US')} characters; the limit is ${MAX_INPUT_LENGTH.toLocaleString('en-US')}.`,
+    }
+  }
+
+  const cleaned = text.replace(NOISE, '')
+  if (cleaned.length === 0) return { error: 'Paste a base64 or hex payload.' }
+
+  let resolved: 'base64' | 'hex'
+  if (encoding === 'auto') {
+    // Hex wins a tie: a string of hex digits is almost always a hex dump,
+    // even though it is also valid base64.
+    resolved = isHexadecimal(cleaned) ? 'hex' : 'base64'
+  } else {
+    resolved = encoding
+  }
+
+  if (resolved === 'hex' && !isHexadecimal(cleaned)) {
+    return {
+      error:
+        cleaned.length % 2 === 1
+          ? 'Hex payload has an odd number of digits.'
+          : 'Payload contains characters that are not hex digits.',
+    }
+  }
+  if (resolved === 'base64' && !isBase64(cleaned)) {
+    return { error: 'Payload is neither valid hex nor valid base64.' }
+  }
+
+  const bytes = resolved === 'hex' ? fromHex(cleaned) : fromBase64(cleaned)
+  if (!bytes) return { error: 'Payload is not valid base64.' }
+  if (bytes.length === 0) return { error: 'Payload decoded to zero bytes.' }
+  if (bytes.length > MAX_PAYLOAD_BYTES) {
+    return {
+      error: `Payload is ${bytes.length.toLocaleString('en-US')} bytes; the limit is ${MAX_PAYLOAD_BYTES.toLocaleString('en-US')}.`,
+    }
+  }
+
+  const frame = readGrpcFrame(bytes)
+  if (frame) {
+    return {
+      bytes: frame.body,
+      encoding: resolved,
+      grpcFrame: { compressed: frame.compressed, length: frame.length },
+    }
+  }
+
+  return { bytes, encoding: resolved }
+}
+
+/** Hex for display, used for byte values the decoder can't read as anything
+ * more specific. */
+export function toHex(bytes: Uint8Array, maxBytes = 32): string {
+  const shown = [...bytes.subarray(0, maxBytes)].map((byte) => byte.toString(16).padStart(2, '0')).join(' ')
+  return bytes.length > maxBytes ? `${shown} … (${bytes.length} bytes)` : shown
+}
diff --git a/src/widgets/protobuf-decoder/protoSchema.test.ts b/src/widgets/protobuf-decoder/protoSchema.test.ts
new file mode 100644
index 0000000..374c500
--- /dev/null
+++ b/src/widgets/protobuf-decoder/protoSchema.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, it } from 'vitest'
+import protobuf from 'protobufjs'
+import { compareWithSchema, decodeWithSchema, MAX_SCHEMA_LENGTH, parseSchema } from './protoSchema'
+import { decodeWireFormat, type WireField } from './wireFormat'
+
+const SCHEMA = `syntax = "proto3";
+package demo;
+
+message Person {
+  int32 id = 1;
+  string name = 2;
+  repeated string tags = 3;
+  Address home = 4;
+  Status status = 5;
+
+  enum Status { UNKNOWN = 0; ACTIVE = 1; }
+  message Address { string city = 1; }
+}
+
+message Team { repeated Person members = 1; }`
+
+function parsed() {
+  const result = parseSchema(SCHEMA)
+  if (!result.ok) throw new Error(result.reason)
+  return result
+}
+
+function encodePerson(value: Record<string, unknown>): Uint8Array {
+  const Person = parsed().root.lookupType('demo.Person')
+  return new Uint8Array(Person.encode(Person.create(value)).finish())
+}
+
+function wireFieldsOf(bytes: Uint8Array): WireField[] {
+  const result = decodeWireFormat(bytes)
+  return result.fields
+}
+
+describe('parseSchema', () => {
+  it('lists every message type, nested ones included, fully qualified', () => {
+    expect(parsed().names).toEqual(['demo.Person', 'demo.Person.Address', 'demo.Team'])
+  })
+
+  it('reports a syntax error with the line it objected to', () => {
+    const result = parseSchema('syntax = "proto3";\nmessage Broken { int32 id = ; }')
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.reason).toMatch(/illegal|token/i)
+      expect(result.line).toBe(2)
+    }
+  })
+
+  it('asks for a definition rather than failing silently on empty input', () => {
+    const result = parseSchema('   ')
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toContain('Paste a .proto definition')
+  })
+
+  it('says so when a definition declares no messages', () => {
+    const result = parseSchema('syntax = "proto3"; enum Color { RED = 0; }')
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toContain('No message types')
+  })
+
+  it('explains that an unresolvable import cannot be fetched in the browser', () => {
+    const result = parseSchema('syntax = "proto3";\nimport "other/thing.proto";\nmessage A { Thing t = 1; }')
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toContain('cannot be resolved in the browser')
+  })
+
+  it('refuses a definition past the size limit', () => {
+    const result = parseSchema('// pad\n'.repeat(MAX_SCHEMA_LENGTH))
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toContain('the limit is 50,000')
+  })
+})
+
+describe('decodeWithSchema', () => {
+  it('names the fields the wire format only numbers', () => {
+    const bytes = encodePerson({ id: 150, name: 'testing', tags: ['a'], home: { city: 'Paris' }, status: 1 })
+    const result = decodeWithSchema(parsed().root, 'demo.Person', bytes)
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.value).toMatchObject({
+      id: 150,
+      name: 'testing',
+      tags: ['a'],
+      home: { city: 'Paris' },
+      // Enums come back as their name, not their number.
+      status: 'ACTIVE',
+    })
+  })
+
+  it('keeps the field names the .proto used, not camelCased ones', () => {
+    const root = protobuf.parse('syntax = "proto3"; message U { int32 user_id = 1; }', { keepCase: true }).root
+    const U = root.lookupType('U')
+    const bytes = new Uint8Array(U.encode(U.create({ user_id: 7 })).finish())
+    const result = decodeWithSchema(root, 'U', bytes)
+    if (!result.ok) throw new Error(result.reason)
+    expect(Object.keys(result.value)).toEqual(['user_id'])
+  })
+
+  it('reports a message name the definition does not have', () => {
+    const result = decodeWithSchema(parsed().root, 'demo.Ghost', new Uint8Array([0x08, 0x01]))
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toContain('No message type named demo.Ghost')
+  })
+
+  it('says the payload may be the wrong message when the decode breaks', () => {
+    // A length prefix promising more bytes than the payload has.
+    const result = decodeWithSchema(parsed().root, 'demo.Person', new Uint8Array([0x12, 0x40, 0x01]))
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toContain('may not be a demo.Person')
+  })
+
+  it('counts fields the payload carries that the definition never declared', () => {
+    // Field 1 (declared) plus field 9 (not in Person).
+    const bytes = new Uint8Array([0x08, 0x96, 0x01, 0x48, 0x2a])
+    const result = decodeWithSchema(parsed().root, 'demo.Person', bytes, wireFieldsOf(bytes))
+    if (!result.ok) throw new Error(result.reason)
+    expect(result.value).toEqual({ id: 150 })
+    // protobufjs drops field 9 silently; the widget must not.
+    expect(result.comparison.unknownFieldNumbers).toEqual([9])
+  })
+
+  it('finds nothing to report when the payload matches the definition', () => {
+    const bytes = encodePerson({ id: 1, name: 'x', tags: ['a'], home: { city: 'Lyon' }, status: 1 })
+    expect(compareWithSchema(parsed().root, 'demo.Person', wireFieldsOf(bytes))).toEqual({
+      unknownFieldNumbers: [],
+      mismatches: [],
+    })
+  })
+
+  it('catches a declared field that arrived as the wrong wire type', () => {
+    // Person's payload read as an Address: field 1 is an int32 here and a
+    // string there, so protobufjs skips it and returns an empty object.
+    const bytes = encodePerson({ id: 150, name: 'testing' })
+    const comparison = compareWithSchema(parsed().root, 'demo.Person.Address', wireFieldsOf(bytes))
+    expect(comparison.mismatches).toEqual([{ fieldNumber: 1, declared: 'string city', wireType: 0 }])
+    expect(comparison.unknownFieldNumbers).toEqual([2])
+
+    const decoded = decodeWithSchema(parsed().root, 'demo.Person.Address', bytes, wireFieldsOf(bytes))
+    if (!decoded.ok) throw new Error(decoded.reason)
+    expect(decoded.value).toEqual({})
+  })
+
+  it('accepts a repeated scalar whether it arrives packed or one tag per item', () => {
+    const root = protobuf.parse('syntax = "proto3"; message C { repeated int32 v = 1; }', { keepCase: true }).root
+    const C = root.lookupType('C')
+    const packed = new Uint8Array(C.encode(C.create({ v: [1, 2, 3] })).finish())
+    expect(compareWithSchema(root, 'C', wireFieldsOf(packed)).mismatches).toEqual([])
+    // The unpacked spelling of the same values: one varint-tagged field each.
+    const unpacked = new Uint8Array([0x08, 0x01, 0x08, 0x02, 0x08, 0x03])
+    expect(compareWithSchema(root, 'C', wireFieldsOf(unpacked)).mismatches).toEqual([])
+  })
+})
diff --git a/src/widgets/protobuf-decoder/protoSchema.ts b/src/widgets/protobuf-decoder/protoSchema.ts
new file mode 100644
index 0000000..f7bda4f
--- /dev/null
+++ b/src/widgets/protobuf-decoder/protoSchema.ts
@@ -0,0 +1,219 @@
+/** Decoding a payload *with* its .proto, using protobufjs to parse the
+ * schema text at runtime.
+ *
+ * Runtime parsing is what makes this work as a widget: there is no codegen
+ * step and no protoc, the .proto is pasted next to the payload and read on
+ * the spot. Everything stays in the browser. */
+
+import protobuf from 'protobufjs'
+import type { WireField } from './wireFormat'
+
+/** A .proto pasted into a widget is a message or two, not a repository. */
+export const MAX_SCHEMA_LENGTH = 50_000
+
+export interface SchemaMessages {
+  ok: true
+  /** Fully qualified message names, package included, in declaration order. */
+  names: string[]
+  root: protobuf.Root
+}
+
+export interface SchemaError {
+  ok: false
+  reason: string
+  /** 1-based line the parser objected to, when it says. */
+  line?: number
+}
+
+/** Parses .proto source and lists the message types it declares.
+ *
+ * Imports are the one thing that cannot work offline: protobufjs resolves
+ * them through the file system, which a browser does not have. The common
+ * `google/protobuf/*` types are bundled with protobufjs and do resolve;
+ * anything else is reported as the missing piece it is. */
+export function parseSchema(source: string): SchemaMessages | SchemaError {
+  if (source.trim().length === 0) return { ok: false, reason: 'Paste a .proto definition, or decode without one.' }
+  if (source.length > MAX_SCHEMA_LENGTH) {
+    return {
+      ok: false,
+      reason: `Definition is ${source.length.toLocaleString('en-US')} characters; the limit is ${MAX_SCHEMA_LENGTH.toLocaleString('en-US')}.`,
+    }
+  }
+
+  let root: protobuf.Root
+  try {
+    // keepCase so a field declared `user_id` is reported as `user_id`
+    // rather than protobufjs's camelCased `userId`, which would not match
+    // the .proto the user is reading beside it.
+    root = protobuf.parse(source, { keepCase: true }).root
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause)
+    const line = message.match(/line (\d+)/)
+    return { ok: false, reason: message, line: line ? Number(line[1]) : undefined }
+  }
+
+  try {
+    root.resolveAll()
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause)
+    // The usual case: an `import` of something that is not bundled.
+    return {
+      ok: false,
+      reason: /no such type|not found/i.test(message)
+        ? `${message}. Imports other than the bundled google/protobuf types cannot be resolved in the browser; paste the imported messages inline.`
+        : message,
+    }
+  }
+
+  const names: string[] = []
+  const walk = (namespace: protobuf.NamespaceBase) => {
+    for (const nested of namespace.nestedArray) {
+      if (nested instanceof protobuf.Type) {
+        names.push(nested.fullName.replace(/^\./, ''))
+        walk(nested)
+      } else if (nested instanceof protobuf.Namespace) {
+        walk(nested)
+      }
+    }
+  }
+  walk(root)
+
+  if (names.length === 0) return { ok: false, reason: 'No message types found in this definition.' }
+  return { ok: true, names, root }
+}
+
+export interface SchemaDecodeSuccess {
+  ok: true
+  /** Plain object, ready for the JSON tree. */
+  value: Record<string, unknown>
+  /** What the wire reading and the message type disagree about. protobufjs
+   * drops both unknown and mismatched fields silently, which is right for a
+   * server and wrong for a debugging tool: a payload that decodes cleanly
+   * while quietly discarding half of itself is exactly the confusion this
+   * widget exists to clear up. */
+  comparison: SchemaComparison
+}
+
+/** Wire types a declared field can legitimately arrive as. A repeated
+ * scalar is the one case with two answers: proto3 packs it into a single
+ * length-delimited field by default, but an older writer may still send one
+ * tagged value per element. */
+function expectedWireTypes(field: protobuf.Field): Set<number> {
+  const scalar: Record<string, number> = {
+    int32: 0,
+    int64: 0,
+    uint32: 0,
+    uint64: 0,
+    sint32: 0,
+    sint64: 0,
+    bool: 0,
+    fixed64: 1,
+    sfixed64: 1,
+    double: 1,
+    string: 2,
+    bytes: 2,
+    fixed32: 5,
+    sfixed32: 5,
+    float: 5,
+  }
+  // An enum is a varint; anything else named is a nested message, which is
+  // length-delimited.
+  const base = scalar[field.type] ?? (field.resolvedType instanceof protobuf.Enum ? 0 : 2)
+  return field.repeated ? new Set([base, 2]) : new Set([base])
+}
+
+export interface SchemaMismatch {
+  fieldNumber: number
+  /** What the .proto declares for that number. */
+  declared: string
+  /** What actually turned up on the wire. */
+  wireType: number
+}
+
+export interface SchemaComparison {
+  /** Field numbers on the wire that the message type says nothing about.
+   * protobufjs drops them silently. */
+  unknownFieldNumbers: number[]
+  /** Declared fields whose wire type does not match their declared type:
+   * the clearest sign the payload is a different message than the one
+   * chosen, since protobufjs skips these without complaining. */
+  mismatches: SchemaMismatch[]
+}
+
+/** Compares the schema-less reading of the same bytes against the message
+ * type, so the two readings check each other rather than being trusted one
+ * at a time. */
+export function compareWithSchema(root: protobuf.Root, messageName: string, wireFields: WireField[]): SchemaComparison {
+  let type: protobuf.Type
+  try {
+    type = root.lookupType(messageName)
+  } catch {
+    return { unknownFieldNumbers: [], mismatches: [] }
+  }
+
+  const declared = new Map(type.fieldsArray.map((field) => [field.id, field]))
+  const unknown = new Set<number>()
+  const mismatches = new Map<number, SchemaMismatch>()
+
+  for (const wireField of wireFields) {
+    const field = declared.get(wireField.fieldNumber)
+    if (!field) {
+      unknown.add(wireField.fieldNumber)
+      continue
+    }
+    if (!expectedWireTypes(field).has(wireField.wireType)) {
+      mismatches.set(wireField.fieldNumber, {
+        fieldNumber: wireField.fieldNumber,
+        declared: `${field.repeated ? 'repeated ' : ''}${field.type} ${field.name}`,
+        wireType: wireField.wireType,
+      })
+    }
+  }
+
+  return {
+    unknownFieldNumbers: [...unknown].sort((a, b) => a - b),
+    mismatches: [...mismatches.values()].sort((a, b) => a.fieldNumber - b.fieldNumber),
+  }
+}
+
+/** Decodes `bytes` as `messageName`. A payload that does not match the
+ * chosen message usually fails loudly (bad wire type, length past the end),
+ * which is the honest answer: it is the wrong message type. */
+export function decodeWithSchema(
+  root: protobuf.Root,
+  messageName: string,
+  bytes: Uint8Array,
+  wireFields: WireField[] = [],
+): SchemaDecodeSuccess | SchemaError {
+  let type: protobuf.Type
+  try {
+    type = root.lookupType(messageName)
+  } catch {
+    return { ok: false, reason: `No message type named ${messageName} in this definition.` }
+  }
+
+  try {
+    const message = type.decode(bytes)
+    return {
+      ok: true,
+      value: type.toObject(message, {
+        // Strings for 64-bit values (they outrun a JS number), base64 for
+        // bytes, names for enums: the readable form in every case.
+        longs: String,
+        bytes: String,
+        enums: String,
+        // No defaults, and no empty arrays or objects for fields the
+        // payload does not carry: the point is to show what is actually on
+        // the wire, not what the message type could hold.
+        defaults: false,
+      }),
+      comparison: compareWithSchema(root, messageName, wireFields),
+    }
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause)
+    return {
+      ok: false,
+      reason: `${message}. The payload may not be a ${messageName}, or may be truncated.`,
+    }
+  }
+}
diff --git a/src/widgets/protobuf-decoder/wireFormat.test.ts b/src/widgets/protobuf-decoder/wireFormat.test.ts
new file mode 100644
index 0000000..174f817
--- /dev/null
+++ b/src/widgets/protobuf-decoder/wireFormat.test.ts
@@ -0,0 +1,167 @@
+import { describe, expect, it } from 'vitest'
+import protobuf from 'protobufjs'
+import { decodeWireFormat, formatFields, WIRE_TYPE_NAMES, type WireField } from './wireFormat'
+
+function bytes(hex: string): Uint8Array {
+  const clean = hex.replace(/\s/g, '')
+  const out = new Uint8Array(clean.length / 2)
+  for (let index = 0; index < out.length; index += 1)
+    out[index] = Number.parseInt(clean.slice(index * 2, index * 2 + 2), 16)
+  return out
+}
+
+function hexOf(bytes: Uint8Array): string {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+function decoded(hex: string): WireField[] {
+  const result = decodeWireFormat(bytes(hex))
+  if (!result.ok) throw new Error(`${result.reason} at ${result.offset}`)
+  return result.fields
+}
+
+describe('decodeWireFormat, varints', () => {
+  it('reads the canonical example from the protobuf docs', () => {
+    // Field 1, varint 150: the encoding every protobuf guide opens with.
+    const [field] = decoded('089601')
+    expect(field.fieldNumber).toBe(1)
+    expect(WIRE_TYPE_NAMES[field.wireType]).toBe('varint')
+    expect(field.value).toMatchObject({ kind: 'varint', value: 150n })
+  })
+
+  it('offers the signed and zigzag readings of the same bits', () => {
+    // -1 as int64 is ten 0xff-ish bytes; as a plain varint it is huge.
+    const [field] = decoded('08ffffffffffffffffff01')
+    if (field.value.kind !== 'varint') throw new Error('expected a varint')
+    expect(field.value.signed).toBe(-1n)
+    expect(field.alternatives).toContain('int64 -1')
+  })
+
+  it('flags a 0 or 1 varint as possibly a bool', () => {
+    const [field] = decoded('0801')
+    expect(field.alternatives).toContain('bool true')
+  })
+})
+
+describe('decodeWireFormat, length-delimited fields', () => {
+  it('reads printable content as a string', () => {
+    const [field] = decoded('120774657374696e67')
+    expect(field.value).toEqual({ kind: 'string', text: 'testing' })
+  })
+
+  it('reads a nested message as structure, and keeps the string reading beside it', () => {
+    // Field 3 holding { 1: 42 }.
+    const [field] = decoded('1a02082a')
+    if (field.value.kind !== 'message') throw new Error('expected a nested message')
+    expect(field.value.fields[0]).toMatchObject({ fieldNumber: 1, value: { kind: 'varint', value: 42n } })
+  })
+
+  it('falls back to bytes for content that is neither, and offers what it might be', () => {
+    const [field] = decoded('1203ff0080')
+    expect(field.value.kind).toBe('bytes')
+  })
+
+  it('reports an empty length-delimited field as ambiguous rather than guessing', () => {
+    const [field] = decoded('1200')
+    expect(field.value.kind).toBe('bytes')
+    expect(field.alternatives).toEqual(['empty string', 'empty message'])
+  })
+
+  it('reads fixed-width fields with both their integer and float meaning', () => {
+    // Field 1, fixed32 holding the float 1.0.
+    const [fixed32] = decoded('0d0000803f')
+    if (fixed32.value.kind !== 'fixed32') throw new Error('expected a fixed32')
+    expect(fixed32.value.float).toBe(1)
+    expect(fixed32.alternatives).toContain('float 1')
+
+    // Field 1, fixed64 holding the double 1.0.
+    const [fixed64] = decoded('09000000000000f03f')
+    if (fixed64.value.kind !== 'fixed64') throw new Error('expected a fixed64')
+    expect(fixed64.value.double).toBe(1)
+  })
+})
+
+describe('decodeWireFormat, round trip against protobufjs', () => {
+  const root = protobuf.parse(
+    `syntax = "proto3";
+     message Person {
+       int32 id = 1;
+       string name = 2;
+       repeated string tags = 3;
+       Address home = 4;
+     }
+     message Address { string city = 1; }`,
+    { keepCase: true },
+  ).root
+  const Person = root.lookupType('Person')
+
+  it('recovers the structure of a message it was never given the schema for', () => {
+    const payload = Person.encode(
+      Person.create({ id: 150, name: 'testing', tags: ['a', 'b'], home: { city: 'Paris' } }),
+    ).finish()
+
+    const result = decodeWireFormat(new Uint8Array(payload))
+    if (!result.ok) throw new Error(result.reason)
+
+    expect(result.fields.map((field) => field.fieldNumber)).toEqual([1, 2, 3, 3, 4])
+    expect(result.fields[0].value).toMatchObject({ kind: 'varint', value: 150n })
+    expect(result.fields[1].value).toEqual({ kind: 'string', text: 'testing' })
+    expect(result.fields[2].value).toEqual({ kind: 'string', text: 'a' })
+    const nested = result.fields[4].value
+    if (nested.kind !== 'message') throw new Error('expected the nested Address')
+    expect(nested.fields[0].value).toEqual({ kind: 'string', text: 'Paris' })
+  })
+
+  it('reads a packed repeated field as bytes, and says it could be packed varints', () => {
+    const packedRoot = protobuf.parse('syntax = "proto3"; message Counts { repeated int32 values = 1; }').root
+    const Counts = packedRoot.lookupType('Counts')
+    const payload = Counts.encode(Counts.create({ values: [300, 400, 500] })).finish()
+
+    const [field] = decoded(hexOf(new Uint8Array(payload)))
+    expect(field.alternatives.some((alternative) => alternative.startsWith('packed varints'))).toBe(true)
+  })
+})
+
+describe('decodeWireFormat, payloads that are not what they claim', () => {
+  it('reports a truncated payload and keeps what it already read', () => {
+    // A valid field, then a length prefix promising bytes that are not there.
+    const result = decodeWireFormat(bytes('0896011209746573'))
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.reason).toContain('past the end')
+    expect(result.fields).toHaveLength(1)
+    expect(result.offset).toBe(3)
+  })
+
+  it('rejects field number 0, which no protobuf writes', () => {
+    const result = decodeWireFormat(bytes('0001'))
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toContain('Field number 0')
+  })
+
+  it('rejects the wire types protobuf never defined', () => {
+    const result = decodeWireFormat(bytes('0e00'))
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toContain('Wire type 6')
+  })
+
+  it('does not run away on deeply nested payloads', () => {
+    // 24 levels of a message wrapping a message, one past the depth guard.
+    let payload = bytes('089601')
+    for (let level = 0; level < 30; level += 1) {
+      const wrapper = new Uint8Array(payload.length + 2)
+      wrapper[0] = 0x0a
+      wrapper[1] = payload.length
+      wrapper.set(payload, 2)
+      payload = wrapper
+    }
+    const result = decodeWireFormat(payload)
+    expect(result.ok).toBe(true)
+  })
+})
+
+describe('formatFields', () => {
+  it('renders nesting as indented blocks', () => {
+    expect(formatFields(decoded('0896011a02082a'))).toBe('1 (varint): 150\n3 (length-delimited) {\n  1 (varint): 42\n}')
+  })
+})
diff --git a/src/widgets/protobuf-decoder/wireFormat.ts b/src/widgets/protobuf-decoder/wireFormat.ts
new file mode 100644
index 0000000..8c5c5d6
--- /dev/null
+++ b/src/widgets/protobuf-decoder/wireFormat.ts
@@ -0,0 +1,321 @@
+/** Schema-less protobuf decoder.
+ *
+ * The wire format keeps field numbers and a 3-bit wire type, and throws the
+ * rest away: names, declared types, and the difference between an int32, a
+ * bool and an enum all live in the .proto, not in the bytes. So a decode
+ * without the schema can always recover the structure, and can only offer
+ * readings of each value. Where more than one reading is valid, the extra
+ * ones ride along on the field so the widget can show them instead of
+ * silently picking one.
+ */
+
+export const WIRE_TYPE_NAMES: Record<number, string> = {
+  0: 'varint',
+  1: '64-bit',
+  2: 'length-delimited',
+  3: 'start group',
+  4: 'end group',
+  5: '32-bit',
+}
+
+export type WireValue =
+  | { kind: 'varint'; value: bigint; signed: bigint; zigzag: bigint }
+  | { kind: 'fixed64'; value: bigint; double: number }
+  | { kind: 'fixed32'; value: number; float: number }
+  | { kind: 'message'; fields: WireField[] }
+  | { kind: 'string'; text: string }
+  | { kind: 'bytes'; bytes: Uint8Array }
+
+export interface WireField {
+  fieldNumber: number
+  wireType: number
+  /** Byte offset of this field's tag, so a row can be traced back to the
+   * payload. */
+  offset: number
+  byteLength: number
+  value: WireValue
+  /** Equally valid readings of the same bytes, e.g. a length-delimited
+   * field that parses as a nested message but is also printable text. */
+  alternatives: string[]
+}
+
+export interface WireDecodeSuccess {
+  ok: true
+  fields: WireField[]
+  byteLength: number
+}
+
+export interface WireDecodeFailure {
+  ok: false
+  reason: string
+  /** Where the decode gave up, so the widget can say how far it got. */
+  offset: number
+  /** Fields read before the failure: a truncated payload is still worth
+   * showing up to the truncation. */
+  fields: WireField[]
+}
+
+/** Nesting guard. protobuf's own default limit is 100; a payload pasted
+ * into a widget never needs that, and a lower bound keeps a pathological
+ * input out of deep recursion. */
+const MAX_DEPTH = 24
+
+function readVarint(bytes: Uint8Array, offset: number): { value: bigint; next: number } | null {
+  let result = 0n
+  let shift = 0n
+  let index = offset
+  while (index < bytes.length) {
+    const byte = bytes[index]
+    index += 1
+    result |= BigInt(byte & 0x7f) << shift
+    if ((byte & 0x80) === 0) return { value: result, next: index }
+    shift += 7n
+    // A varint is at most 10 bytes; anything longer is not one.
+    if (shift > 63n) return null
+  }
+  return null
+}
+
+/** Two's-complement reading of the same 64 bits, which is how a negative
+ * int32/int64 travels. */
+function asSigned(value: bigint): bigint {
+  return BigInt.asIntN(64, value)
+}
+
+/** ZigZag is how sint32/sint64 encode negatives compactly, and it gives a
+ * different number from the plain reading, so both are offered. */
+function asZigZag(value: bigint): bigint {
+  return (value >> 1n) ^ -(value & 1n)
+}
+
+const utf8 = new TextDecoder('utf-8', { fatal: true })
+
+function readUtf8(bytes: Uint8Array): string | null {
+  try {
+    return utf8.decode(bytes)
+  } catch {
+    return null
+  }
+}
+
+/** Text worth preferring over a nested-message reading: no control
+ * characters, no replacement characters, and not empty. */
+function isCleanText(text: string): boolean {
+  if (text.length === 0) return false
+  for (const character of text) {
+    const code = character.codePointAt(0) ?? 0
+    const isControl = code < 0x20 && code !== 0x09 && code !== 0x0a && code !== 0x0d
+    if (isControl || code === 0x7f || code === 0xfffd) return false
+  }
+  return true
+}
+
+/** A packed repeated field is varints back to back with no tags, so that
+ * reading is offered whenever the bytes happen to be exactly that. */
+function readPackedVarints(bytes: Uint8Array): bigint[] | null {
+  const values: bigint[] = []
+  let offset = 0
+  while (offset < bytes.length) {
+    const varint = readVarint(bytes, offset)
+    if (!varint) return null
+    values.push(varint.value)
+    offset = varint.next
+  }
+  return values.length > 0 ? values : null
+}
+
+export function describeValue(value: WireValue): string {
+  switch (value.kind) {
+    case 'varint':
+      return String(value.value)
+    case 'fixed64':
+      return String(value.value)
+    case 'fixed32':
+      return String(value.value)
+    case 'string':
+      return JSON.stringify(value.text)
+    case 'bytes':
+      return `${value.bytes.length} bytes`
+    case 'message':
+      return `${value.fields.length} field${value.fields.length === 1 ? '' : 's'}`
+  }
+}
+
+interface ParseOutcome {
+  fields: WireField[]
+  /** Set when parsing stopped early; absent on a clean parse. */
+  failure?: { reason: string; offset: number }
+}
+
+/** Reads fields from `[from, to)`. Stops at the first byte that cannot be a
+ * field, reporting where; callers deciding whether a region *is* a message
+ * treat any failure as "no". */
+function parseFields(bytes: Uint8Array, from: number, to: number, depth: number): ParseOutcome {
+  const fields: WireField[] = []
+  let offset = from
+
+  while (offset < to) {
+    const start = offset
+    const tag = readVarint(bytes, offset)
+    if (!tag || tag.next > to) return { fields, failure: { reason: 'Truncated field tag.', offset: start } }
+
+    const fieldNumber = Number(tag.value >> 3n)
+    const wireType = Number(tag.value & 7n)
+    offset = tag.next
+
+    if (fieldNumber === 0) {
+      return { fields, failure: { reason: 'Field number 0 is not valid protobuf.', offset: start } }
+    }
+    if (wireType === 6 || wireType === 7) {
+      return { fields, failure: { reason: `Wire type ${wireType} is not valid protobuf.`, offset: start } }
+    }
+    if (wireType === 4) {
+      // An end-group marker with no group open.
+      return { fields, failure: { reason: 'Unexpected end-group marker.', offset: start } }
+    }
+
+    if (wireType === 0) {
+      const varint = readVarint(bytes, offset)
+      if (!varint || varint.next > to) {
+        return { fields, failure: { reason: 'Truncated varint.', offset: start } }
+      }
+      const alternatives: string[] = []
+      if (varint.value === 0n || varint.value === 1n) alternatives.push(`bool ${varint.value === 1n}`)
+      if (asSigned(varint.value) !== varint.value) alternatives.push(`int64 ${asSigned(varint.value)}`)
+      if (asZigZag(varint.value) !== varint.value) alternatives.push(`sint64 ${asZigZag(varint.value)}`)
+      fields.push({
+        fieldNumber,
+        wireType,
+        offset: start,
+        byteLength: varint.next - start,
+        value: { kind: 'varint', value: varint.value, signed: asSigned(varint.value), zigzag: asZigZag(varint.value) },
+        alternatives,
+      })
+      offset = varint.next
+      continue
+    }
+
+    if (wireType === 1 || wireType === 5) {
+      const width = wireType === 1 ? 8 : 4
+      if (offset + width > to) {
+        return { fields, failure: { reason: `Truncated ${width * 8}-bit value.`, offset: start } }
+      }
+      const view = new DataView(bytes.buffer, bytes.byteOffset + offset, width)
+      const value: WireValue =
+        wireType === 1
+          ? { kind: 'fixed64', value: view.getBigUint64(0, true), double: view.getFloat64(0, true) }
+          : { kind: 'fixed32', value: view.getUint32(0, true), float: view.getFloat32(0, true) }
+      const alternatives =
+        value.kind === 'fixed64'
+          ? [`double ${value.double}`, `sfixed64 ${BigInt.asIntN(64, value.value)}`]
+          : [`float ${value.float}`, `sfixed32 ${value.value | 0}`]
+      fields.push({ fieldNumber, wireType, offset: start, byteLength: offset + width - start, value, alternatives })
+      offset += width
+      continue
+    }
+
+    if (wireType === 3) {
+      // Groups are a proto2 relic, but they still turn up in old payloads:
+      // everything up to the matching end-group tag belongs to this field.
+      const inner = parseFields(bytes, offset, to, depth + 1)
+      const closed = inner.failure?.reason === 'Unexpected end-group marker.'
+      return {
+        fields: [
+          ...fields,
+          {
+            fieldNumber,
+            wireType,
+            offset: start,
+            byteLength: to - start,
+            value: { kind: 'message', fields: inner.fields },
+            alternatives: ['deprecated group encoding'],
+          },
+        ],
+        failure: closed ? undefined : inner.failure,
+      }
+    }
+
+    // Wire type 2: length-delimited.
+    const length = readVarint(bytes, offset)
+    if (!length) return { fields, failure: { reason: 'Truncated length prefix.', offset: start } }
+    const contentStart = length.next
+    const contentEnd = contentStart + Number(length.value)
+    if (contentEnd > to) {
+      return { fields, failure: { reason: 'Length runs past the end of the payload.', offset: start } }
+    }
+
+    const interpreted = interpretLengthDelimited(bytes, contentStart, contentEnd, depth)
+    fields.push({
+      fieldNumber,
+      wireType,
+      offset: start,
+      byteLength: contentEnd - start,
+      value: interpreted.value,
+      alternatives: interpreted.alternatives,
+    })
+    offset = contentEnd
+  }
+
+  return { fields }
+}
+
+function interpretLengthDelimited(
+  bytes: Uint8Array,
+  from: number,
+  to: number,
+  depth: number,
+): { value: WireValue; alternatives: string[] } {
+  const content = bytes.subarray(from, to)
+  const alternatives: string[] = []
+
+  if (content.length === 0) {
+    return { value: { kind: 'bytes', bytes: content }, alternatives: ['empty string', 'empty message'] }
+  }
+
+  const text = readUtf8(content)
+  const nested = depth < MAX_DEPTH ? parseFields(bytes, from, to, depth + 1) : { fields: [], failure: undefined }
+  const parsesAsMessage = !nested.failure && nested.fields.length > 0
+
+  if (parsesAsMessage) {
+    // Prefer the structure, and keep the text reading alongside it: the two
+    // are genuinely ambiguous, and only the schema settles which was meant.
+    if (text !== null && isCleanText(text)) alternatives.push(`string ${JSON.stringify(text)}`)
+    return { value: { kind: 'message', fields: nested.fields }, alternatives }
+  }
+
+  if (text !== null && isCleanText(text)) {
+    return { value: { kind: 'string', text }, alternatives }
+  }
+
+  const packed = readPackedVarints(content)
+  if (packed && packed.length > 1) {
+    alternatives.push(`packed varints ${packed.slice(0, 8).join(', ')}${packed.length > 8 ? ', …' : ''}`)
+  }
+  if (text !== null) alternatives.push(`string ${JSON.stringify(text)}`)
+  return { value: { kind: 'bytes', bytes: content }, alternatives }
+}
+
+/** Decodes a payload without a schema. A truncated or non-protobuf payload
+ * still returns whatever was read before the trouble, since a partial
+ * decode is usually enough to recognize what you are looking at. */
+export function decodeWireFormat(bytes: Uint8Array): WireDecodeSuccess | WireDecodeFailure {
+  const outcome = parseFields(bytes, 0, bytes.length, 0)
+  if (outcome.failure) {
+    return { ok: false, reason: outcome.failure.reason, offset: outcome.failure.offset, fields: outcome.fields }
+  }
+  return { ok: true, fields: outcome.fields, byteLength: bytes.length }
+}
+
+/** Flat text rendering of decoded fields, for the copy button. */
+export function formatFields(fields: WireField[], indent = 0): string {
+  const pad = '  '.repeat(indent)
+  return fields
+    .map((field) => {
+      const head = `${pad}${field.fieldNumber} (${WIRE_TYPE_NAMES[field.wireType]})`
+      if (field.value.kind === 'message') {
+        return `${head} {\n${formatFields(field.value.fields, indent + 1)}\n${pad}}`
+      }
+      return `${head}: ${describeValue(field.value)}`
+    })
+    .join('\n')
+}
diff --git a/src/widgets/registry.ts b/src/widgets/registry.ts
index 3a776ec..110ae15 100644
--- a/src/widgets/registry.ts
+++ b/src/widgets/registry.ts
@@ -34,6 +34,7 @@ import { logViewerDefinition } from './log-viewer/definition'
 import { lzStringDefinition } from './lz-string/definition'
 import { unixPermissionsDefinition } from './unix-permissions/definition'
 import { timelineBuilderDefinition } from './timeline-builder/definition'
+import { protobufDecoderDefinition } from './protobuf-decoder/definition'
 
 /** Single source of truth for every widget localgrid knows about. The
  * dashboard grid, tool browser, and command palette all read from this. */
@@ -73,6 +74,7 @@ const ALL_WIDGETS: WidgetDefinition[] = [
   lzStringDefinition,
   unixPermissionsDefinition,
   timelineBuilderDefinition,
+  protobufDecoderDefinition,
 ]
 
 export const WIDGET_REGISTRY: Record<string, WidgetDefinition> = Object.fromEntries(

From d4efece0aa8218cfe3663583597de38dd63397d7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 16 Sep 2026 18:36:31 +0000
Subject: [PATCH 2/2] fix(protobuf-decoder): address review findings

- Keep `0x` until the encoding is settled. `0`, `x` and `X` are all base64
  characters, so stripping the hex marker up front rewrote base64
  payloads: '0x' became the empty-input error and '0xAA' decoded as 'AA'.
  The marker is now removed only from the hex candidate, which keeps auto
  mode reading '0x08, 0x96' as hex.
- Guard the group branch with MAX_DEPTH. A group tag costs one byte per
  level, so a run of 0x0b bytes recursed once per byte and overflowed the
  stack with an uncaught RangeError.
- Keep decoding after a group closes, and charge the group only its own
  bytes. The branch returned instead of continuing, so every field after
  the end-group tag was silently dropped, and byteLength claimed the group
  covered the rest of the payload. parseFields now reports the offset it
  stopped at, an end-group tag closes the group it belongs to, and a
  mismatched or unclosed group is reported rather than passing as clean.
- Empty the Copy button in schema mode when the decode failed, instead of
  falling through to the schema-less rendering the pane is not showing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K2aiBGNxfoFs9oBpSVBTsE
---
 .../ProtobufDecoderWidget.tsx                 |  5 +-
 .../protobuf-decoder/payloadBytes.test.ts     | 16 ++++
 src/widgets/protobuf-decoder/payloadBytes.ts  | 23 +++--
 .../protobuf-decoder/wireFormat.test.ts       | 40 ++++++++
 src/widgets/protobuf-decoder/wireFormat.ts    | 93 +++++++++++++------
 5 files changed, 139 insertions(+), 38 deletions(-)

diff --git a/src/widgets/protobuf-decoder/ProtobufDecoderWidget.tsx b/src/widgets/protobuf-decoder/ProtobufDecoderWidget.tsx
index 0ddd7be..1cf6f7c 100644
--- a/src/widgets/protobuf-decoder/ProtobufDecoderWidget.tsx
+++ b/src/widgets/protobuf-decoder/ProtobufDecoderWidget.tsx
@@ -68,7 +68,10 @@ export default function ProtobufDecoderWidget({ instanceId }: WidgetProps) {
   }, [mode, bytes, parsedSchema, selectedName, wire])
 
   const copyText = useMemo(() => {
-    if (mode === 'schema' && schemaDecode?.ok) return JSON.stringify(schemaDecode.value, null, 2)
+    // Branching on the mode first matters: with a failed schema decode the
+    // pane shows an error, and falling through to the wire rendering would
+    // have the Copy button hand back output nobody can see.
+    if (mode === 'schema') return schemaDecode?.ok ? JSON.stringify(schemaDecode.value, null, 2) : ''
     return wire ? formatFields(wire.fields) : ''
   }, [mode, schemaDecode, wire])
 
diff --git a/src/widgets/protobuf-decoder/payloadBytes.test.ts b/src/widgets/protobuf-decoder/payloadBytes.test.ts
index 544b4ce..7fd29a1 100644
--- a/src/widgets/protobuf-decoder/payloadBytes.test.ts
+++ b/src/widgets/protobuf-decoder/payloadBytes.test.ts
@@ -21,6 +21,22 @@ describe('decodePayload', () => {
     expect(bytesOf(decodePayload('-_8'))).toEqual(bytesOf(decodePayload('+/8=')))
   })
 
+  it('leaves 0x alone in a base64 payload', () => {
+    // 0, x and X are all base64 characters, so stripping "0x" before the
+    // encoding was settled rewrote the payload: '0x' decoded as the empty
+    // input error, and '0xAA' decoded as 'AA'.
+    const fromBase64 = (text: string) =>
+      [...atob(text.padEnd(text.length + ((4 - (text.length % 4)) % 4), '='))].map((character) =>
+        character.charCodeAt(0),
+      )
+    expect(bytesOf(decodePayload('0x', 'base64'))).toEqual(fromBase64('0x'))
+    expect(bytesOf(decodePayload('0xAA', 'base64'))).toEqual(fromBase64('0xAA'))
+    expect(bytesOf(decodePayload('0xAA', 'base64'))).not.toEqual(fromBase64('AA'))
+    // '0x+/' is not valid hex once the marker is removed, so auto keeps it
+    // as base64, and must not have mangled it on the way.
+    expect(bytesOf(decodePayload('0x+/'))).toEqual(fromBase64('0x+/'))
+  })
+
   it('prefers hex when the text is valid as both', () => {
     const result = decodePayload('089601')
     expect('error' in result ? null : result.encoding).toBe('hex')
diff --git a/src/widgets/protobuf-decoder/payloadBytes.ts b/src/widgets/protobuf-decoder/payloadBytes.ts
index 2c2c6d4..adc4501 100644
--- a/src/widgets/protobuf-decoder/payloadBytes.ts
+++ b/src/widgets/protobuf-decoder/payloadBytes.ts
@@ -20,9 +20,14 @@ export interface PayloadError {
 }
 
 /** Characters that carry no information in either encoding: whitespace from
- * wrapped lines, `0x` prefixes and separators from hex dumps, quotes and
- * commas from a pasted code literal. */
-const NOISE = /[\s,"'`]|0x/gi
+ * wrapped lines, quotes and commas from a pasted code literal. */
+const PRESENTATION_NOISE = /[\s,"'`]/g
+
+/** The `0x` markers of a hex dump. Stripped only once the payload is known
+ * to be hex: `0`, `x` and `X` are all valid base64 characters, so removing
+ * them up front would quietly rewrite a base64 payload that happens to
+ * contain them. */
+const HEX_PREFIX = /0x/gi
 
 /** Both limits are about keeping a paste from stalling the tab rather than
  * about protobuf itself: the decode is linear, but every field becomes a
@@ -84,18 +89,22 @@ export function decodePayload(text: string, encoding: PayloadEncoding = 'auto'):
     }
   }
 
-  const cleaned = text.replace(NOISE, '')
-  if (cleaned.length === 0) return { error: 'Paste a base64 or hex payload.' }
+  const normalized = text.replace(PRESENTATION_NOISE, '')
+  if (normalized.length === 0) return { error: 'Paste a base64 or hex payload.' }
+  const withoutHexPrefixes = normalized.replace(HEX_PREFIX, '')
 
   let resolved: 'base64' | 'hex'
   if (encoding === 'auto') {
     // Hex wins a tie: a string of hex digits is almost always a hex dump,
-    // even though it is also valid base64.
-    resolved = isHexadecimal(cleaned) ? 'hex' : 'base64'
+    // even though it is also valid base64. The candidate tested here is the
+    // one with `0x` markers removed, so `0x08 0x96` is still read as hex.
+    resolved = isHexadecimal(withoutHexPrefixes) ? 'hex' : 'base64'
   } else {
     resolved = encoding
   }
 
+  const cleaned = resolved === 'hex' ? withoutHexPrefixes : normalized
+
   if (resolved === 'hex' && !isHexadecimal(cleaned)) {
     return {
       error:
diff --git a/src/widgets/protobuf-decoder/wireFormat.test.ts b/src/widgets/protobuf-decoder/wireFormat.test.ts
index 174f817..b58a30d 100644
--- a/src/widgets/protobuf-decoder/wireFormat.test.ts
+++ b/src/widgets/protobuf-decoder/wireFormat.test.ts
@@ -160,6 +160,46 @@ describe('decodeWireFormat, payloads that are not what they claim', () => {
   })
 })
 
+describe('decodeWireFormat, groups', () => {
+  // Proto2 groups: 0x0b is field 1 start-group, 0x0c its end-group tag.
+  it('keeps decoding after a group closes, and charges it only its own bytes', () => {
+    // group 1 { 2: 150 }, then field 3 varint 7.
+    const fields = decoded('0b 10 96 01 0c 18 07')
+    expect(fields.map((field) => field.fieldNumber)).toEqual([1, 3])
+
+    const group = fields[0]
+    expect(group.value).toMatchObject({ kind: 'message' })
+    if (group.value.kind !== 'message') throw new Error('expected a group')
+    expect(group.value.fields[0]).toMatchObject({ fieldNumber: 2, value: { kind: 'varint', value: 150n } })
+    // Tag, body and end-group tag: five bytes, not the rest of the payload.
+    expect(group.byteLength).toBe(5)
+
+    expect(fields[1].value).toMatchObject({ kind: 'varint', value: 7n })
+  })
+
+  it('reports a group that never closes', () => {
+    const result = decodeWireFormat(bytes('0b 10 96 01'))
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toContain('never closed')
+  })
+
+  it('reports an end-group tag that closes a different field', () => {
+    // Opens group 1, closes group 2.
+    const result = decodeWireFormat(bytes('0b 10 96 01 14'))
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toContain('Mismatched end-group')
+  })
+
+  it('stops instead of overflowing the stack on a run of start-group tags', () => {
+    // Every 0x0b opens a group and consumes one byte, so without a depth
+    // guard the recursion depth equals the payload length.
+    const payload = new Uint8Array(5000).fill(0x0b)
+    const result = decodeWireFormat(payload)
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toContain('too deep')
+  })
+})
+
 describe('formatFields', () => {
   it('renders nesting as indented blocks', () => {
     expect(formatFields(decoded('0896011a02082a'))).toBe('1 (varint): 150\n3 (length-delimited) {\n  1 (varint): 42\n}')
diff --git a/src/widgets/protobuf-decoder/wireFormat.ts b/src/widgets/protobuf-decoder/wireFormat.ts
index 8c5c5d6..117f93f 100644
--- a/src/widgets/protobuf-decoder/wireFormat.ts
+++ b/src/widgets/protobuf-decoder/wireFormat.ts
@@ -143,41 +143,64 @@ export function describeValue(value: WireValue): string {
 
 interface ParseOutcome {
   fields: WireField[]
+  /** Offset just past the last byte this parse consumed. A group needs it
+   * to know where its own end-group tag left off, so the fields after the
+   * group are not lost and the group's own length is the real one. */
+  end: number
   /** Set when parsing stopped early; absent on a clean parse. */
   failure?: { reason: string; offset: number }
 }
 
 /** Reads fields from `[from, to)`. Stops at the first byte that cannot be a
  * field, reporting where; callers deciding whether a region *is* a message
- * treat any failure as "no". */
-function parseFields(bytes: Uint8Array, from: number, to: number, depth: number): ParseOutcome {
+ * treat any failure as "no".
+ *
+ * `openGroup` is the field number of the group being read, when this call
+ * is reading one: the matching end-group tag then ends this parse cleanly
+ * instead of being the error it is anywhere else. */
+function parseFields(
+  bytes: Uint8Array,
+  from: number,
+  to: number,
+  depth: number,
+  openGroup: number | null = null,
+): ParseOutcome {
   const fields: WireField[] = []
   let offset = from
 
   while (offset < to) {
     const start = offset
     const tag = readVarint(bytes, offset)
-    if (!tag || tag.next > to) return { fields, failure: { reason: 'Truncated field tag.', offset: start } }
+    if (!tag || tag.next > to) return { fields, end: start, failure: { reason: 'Truncated field tag.', offset: start } }
 
     const fieldNumber = Number(tag.value >> 3n)
     const wireType = Number(tag.value & 7n)
     offset = tag.next
 
     if (fieldNumber === 0) {
-      return { fields, failure: { reason: 'Field number 0 is not valid protobuf.', offset: start } }
+      return { fields, end: start, failure: { reason: 'Field number 0 is not valid protobuf.', offset: start } }
     }
     if (wireType === 6 || wireType === 7) {
-      return { fields, failure: { reason: `Wire type ${wireType} is not valid protobuf.`, offset: start } }
+      return { fields, end: start, failure: { reason: `Wire type ${wireType} is not valid protobuf.`, offset: start } }
     }
     if (wireType === 4) {
-      // An end-group marker with no group open.
-      return { fields, failure: { reason: 'Unexpected end-group marker.', offset: start } }
+      // The tag that closes the group this call is reading; anywhere else
+      // it is a payload that does not add up.
+      if (openGroup === fieldNumber) return { fields, end: offset }
+      return {
+        fields,
+        end: start,
+        failure: {
+          reason: openGroup === null ? 'Unexpected end-group marker.' : 'Mismatched end-group marker.',
+          offset: start,
+        },
+      }
     }
 
     if (wireType === 0) {
       const varint = readVarint(bytes, offset)
       if (!varint || varint.next > to) {
-        return { fields, failure: { reason: 'Truncated varint.', offset: start } }
+        return { fields, end: start, failure: { reason: 'Truncated varint.', offset: start } }
       }
       const alternatives: string[] = []
       if (varint.value === 0n || varint.value === 1n) alternatives.push(`bool ${varint.value === 1n}`)
@@ -198,7 +221,7 @@ function parseFields(bytes: Uint8Array, from: number, to: number, depth: number)
     if (wireType === 1 || wireType === 5) {
       const width = wireType === 1 ? 8 : 4
       if (offset + width > to) {
-        return { fields, failure: { reason: `Truncated ${width * 8}-bit value.`, offset: start } }
+        return { fields, end: start, failure: { reason: `Truncated ${width * 8}-bit value.`, offset: start } }
       }
       const view = new DataView(bytes.buffer, bytes.byteOffset + offset, width)
       const value: WireValue =
@@ -215,33 +238,35 @@ function parseFields(bytes: Uint8Array, from: number, to: number, depth: number)
     }
 
     if (wireType === 3) {
+      // A group costs one byte per level, so without this guard a run of
+      // 0x0b bytes recurses once per byte and overflows the stack.
+      if (depth >= MAX_DEPTH) {
+        return { fields, end: start, failure: { reason: 'Group nesting is too deep.', offset: start } }
+      }
       // Groups are a proto2 relic, but they still turn up in old payloads:
       // everything up to the matching end-group tag belongs to this field.
-      const inner = parseFields(bytes, offset, to, depth + 1)
-      const closed = inner.failure?.reason === 'Unexpected end-group marker.'
-      return {
-        fields: [
-          ...fields,
-          {
-            fieldNumber,
-            wireType,
-            offset: start,
-            byteLength: to - start,
-            value: { kind: 'message', fields: inner.fields },
-            alternatives: ['deprecated group encoding'],
-          },
-        ],
-        failure: closed ? undefined : inner.failure,
-      }
+      const inner = parseFields(bytes, offset, to, depth + 1, fieldNumber)
+      fields.push({
+        fieldNumber,
+        wireType,
+        offset: start,
+        byteLength: inner.end - start,
+        value: { kind: 'message', fields: inner.fields },
+        alternatives: ['deprecated group encoding'],
+      })
+      if (inner.failure) return { fields, end: inner.end, failure: inner.failure }
+      // Whatever follows the end-group tag is still part of this message.
+      offset = inner.end
+      continue
     }
 
     // Wire type 2: length-delimited.
     const length = readVarint(bytes, offset)
-    if (!length) return { fields, failure: { reason: 'Truncated length prefix.', offset: start } }
+    if (!length) return { fields, end: start, failure: { reason: 'Truncated length prefix.', offset: start } }
     const contentStart = length.next
     const contentEnd = contentStart + Number(length.value)
     if (contentEnd > to) {
-      return { fields, failure: { reason: 'Length runs past the end of the payload.', offset: start } }
+      return { fields, end: start, failure: { reason: 'Length runs past the end of the payload.', offset: start } }
     }
 
     const interpreted = interpretLengthDelimited(bytes, contentStart, contentEnd, depth)
@@ -256,7 +281,14 @@ function parseFields(bytes: Uint8Array, from: number, to: number, depth: number)
     offset = contentEnd
   }
 
-  return { fields }
+  if (openGroup !== null) {
+    return {
+      fields,
+      end: offset,
+      failure: { reason: 'Group is never closed.', offset: from },
+    }
+  }
+  return { fields, end: offset }
 }
 
 function interpretLengthDelimited(
@@ -273,8 +305,9 @@ function interpretLengthDelimited(
   }
 
   const text = readUtf8(content)
-  const nested = depth < MAX_DEPTH ? parseFields(bytes, from, to, depth + 1) : { fields: [], failure: undefined }
-  const parsesAsMessage = !nested.failure && nested.fields.length > 0
+  const nested =
+    depth < MAX_DEPTH ? parseFields(bytes, from, to, depth + 1) : { fields: [], end: from, failure: undefined }
+  const parsesAsMessage = !nested.failure && nested.fields.length > 0 && nested.end === to
 
   if (parsesAsMessage) {
     // Prefer the structure, and keep the text reading alongside it: the two