@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/payload-inspector/payload-inspector.css

@@ -0,0 +1,173 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+
+@layer cinder.components {
+  .cinder-payload-inspector {
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-0);
+    border: 1px solid var(--cinder-border-muted);
+    border-radius: var(--cinder-radius-md);
+    overflow: hidden;
+    background: var(--cinder-surface);
+    font-size: var(--cinder-text-sm);
+  }
+
+  /* ----------------------------------------
+   * Header bar
+   * ---------------------------------------- */
+
+  .cinder-payload-inspector__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--cinder-space-2);
+    padding: var(--cinder-space-2) var(--cinder-space-3);
+    background: var(--cinder-surface-raised);
+    border-bottom: 1px solid var(--cinder-border-muted);
+    flex-wrap: wrap;
+  }
+
+  .cinder-payload-inspector__label {
+    font-size: var(--cinder-text-xs);
+    font-weight: var(--cinder-font-medium);
+    color: var(--cinder-text-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+
+  .cinder-payload-inspector__header-actions {
+    display: flex;
+    align-items: center;
+    gap: var(--cinder-space-2);
+    flex-wrap: wrap;
+  }
+
+  .cinder-payload-inspector__size {
+    font-size: var(--cinder-text-xs);
+    color: var(--cinder-text-muted);
+    font-variant-numeric: tabular-nums;
+  }
+
+  /* ----------------------------------------
+   * Tab list within inspector
+   * ---------------------------------------- */
+
+  .cinder-payload-inspector__tabs {
+    display: flex;
+    flex-direction: column;
+    flex: 1;
+    min-block-size: 0;
+  }
+
+  /* ----------------------------------------
+   * Panel content areas
+   * ---------------------------------------- */
+
+  .cinder-payload-inspector__panel {
+    padding: var(--cinder-space-4);
+    overflow: auto;
+  }
+
+  .cinder-payload-inspector__panel--code {
+    padding: var(--cinder-space-0);
+  }
+
+  /* ----------------------------------------
+   * Raw view (CodeBlock wrapper)
+   * ---------------------------------------- */
+
+  .cinder-payload-inspector__raw {
+    /* Remove the built-in CodeBlock rounded corners so the block sits flush
+       inside the panel. Border radius is handled by the outer inspector. */
+    border-radius: 0;
+  }
+
+  /* ----------------------------------------
+   * Summary view
+   * ---------------------------------------- */
+
+  .cinder-payload-inspector__summary {
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-4);
+  }
+
+  .cinder-payload-inspector__summary-badges {
+    display: flex;
+    align-items: center;
+    gap: var(--cinder-space-2);
+    flex-wrap: wrap;
+  }
+
+  .cinder-payload-inspector__summary-value {
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-2);
+  }
+
+  .cinder-payload-inspector__summary-value-label {
+    font-size: var(--cinder-text-xs);
+    font-weight: var(--cinder-font-medium);
+    color: var(--cinder-text-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+
+  .cinder-payload-inspector__primitive {
+    font-family: var(--cinder-font-mono);
+    font-size: var(--cinder-text-sm);
+    color: var(--cinder-text);
+    background: var(--cinder-surface-raised);
+    padding: var(--cinder-space-2) var(--cinder-space-3);
+    border-radius: var(--cinder-radius-sm);
+    border: 1px solid var(--cinder-border-muted);
+    word-break: break-all;
+  }
+
+  /* ----------------------------------------
+   * Notices and placeholders
+   * ---------------------------------------- */
+
+  .cinder-payload-inspector__notice {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--cinder-space-2);
+    padding: var(--cinder-space-3);
+    background: var(--cinder-surface-raised);
+    border-radius: var(--cinder-radius-sm);
+    border: 1px solid var(--cinder-border-muted);
+    color: var(--cinder-text-muted);
+    font-size: var(--cinder-text-sm);
+  }
+
+  .cinder-payload-inspector__notice--warning {
+    background: var(--cinder-color-warning-bg);
+    border-color: var(--cinder-color-warning-border);
+    color: var(--cinder-color-warning-fg);
+  }
+
+  .cinder-payload-inspector__empty {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: var(--cinder-space-8) var(--cinder-space-4);
+    color: var(--cinder-text-disabled);
+    font-size: var(--cinder-text-sm);
+    font-style: italic;
+  }
+
+  /* ----------------------------------------
+   * Focus ring on focusable elements we own
+   * ---------------------------------------- */
+
+  .cinder-payload-inspector:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: var(--_cinder-focus-ring-shadow);
+  }
+
+  @media (forced-colors: active) {
+    .cinder-payload-inspector:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+    }
+  }
+}

package/src/components/payload-inspector/payload-inspector.examples.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "payload-inspector",
+  "import": "@lostgradient/cinder/payload-inspector",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic payload inspector",
+      "description": "Inspect a structured object payload with summary metadata, interactive tree, and raw JSON views.",
+      "code": "<script lang=\"ts\">\n  import { PayloadInspector } from '@lostgradient/cinder/payload-inspector';\n\n  const payload = {\n    userId: 'u_8f2a3b',\n    action: 'checkout',\n    cart: {\n      items: [\n        { id: 'p_001', name: 'Widget', qty: 2, price: 19.99 },\n        { id: 'p_002', name: 'Gadget', qty: 1, price: 49.95 },\n      ],\n      total: 89.93,\n    },\n    timestamp: '2026-06-11T14:22:00Z',\n    flags: { guestCheckout: false, promoApplied: true },\n  };\n</script>\n\n<PayloadInspector\n  value={payload}\n  meta={{\n    contentType: 'application/json',\n    source: 'checkout-workflow',\n    timestamp: '2026-06-11T14:22:00Z',\n  }}\n/>\n"
+    },
+    {
+      "id": "edge-cases",
+      "title": "Edge cases",
+      "description": "Demonstrates null, invalid JSON, and empty payload states in the inspector.",
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { PayloadInspector } from '@lostgradient/cinder/payload-inspector';\n\n  type Scenario = 'empty' | 'null' | 'invalid-json' | 'truncated' | 'primitive';\n\n  let scenario = $state<Scenario>('empty');\n\n  const scenarios: Record<Scenario, { value?: unknown; truncated?: boolean; label: string }> = {\n    empty: { value: undefined, label: 'No payload' },\n    null: { value: null, label: 'Null value' },\n    'invalid-json': { value: '{ not valid json at all', label: 'Invalid JSON string' },\n    truncated: { value: { partial: 'data', more: '...' }, truncated: true, label: 'Truncated' },\n    primitive: { value: 42, label: 'Number primitive' },\n  };\n\n  const current = $derived(scenarios[scenario]);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <div style=\"display: flex; gap: 0.5rem; flex-wrap: wrap;\">\n    {#each Object.keys(scenarios) as key (key)}\n      <Button\n        variant={scenario === key ? 'primary' : 'secondary'}\n        size=\"sm\"\n        onclick={() => (scenario = key as Scenario)}\n      >\n        {scenarios[key as Scenario].label}\n      </Button>\n    {/each}\n  </div>\n\n  <PayloadInspector\n    value={current.value}\n    truncated={current.truncated ?? false}\n    meta={{ source: 'edge-case-demo' }}\n  />\n</div>\n"
+    },
+    {
+      "id": "signal-payload",
+      "title": "Signal payload",
+      "description": "Inspect a workflow signal payload — a common pattern in activity result dashboards.",
+      "code": "<script lang=\"ts\">\n  import { PayloadInspector } from '@lostgradient/cinder/payload-inspector';\n\n  const signalPayload = {\n    signalName: 'PaymentConfirmed',\n    data: {\n      transactionId: 'txn_5e8b2a',\n      amount: 89.93,\n      currency: 'USD',\n      provider: 'stripe',\n      confirmedAt: '2026-06-11T14:23:01Z',\n      metadata: {\n        statementDescriptor: 'ACME STORE',\n        riskScore: 0.12,\n      },\n    },\n    sentAt: '2026-06-11T14:23:01.543Z',\n    correlationId: 'ord_9c4e1f',\n  };\n</script>\n\n<PayloadInspector\n  value={signalPayload}\n  meta={{\n    contentType: 'application/json',\n    source: 'payment-service',\n    timestamp: '2026-06-11T14:23:01Z',\n  }}\n/>\n"
+    },
+    {
+      "id": "workflow-input",
+      "title": "Workflow input",
+      "description": "Inspecting a workflow launch payload with signal input, retry policy, and schedule metadata.",
+      "code": "<script lang=\"ts\">\n  import { PayloadInspector } from '@lostgradient/cinder/payload-inspector';\n\n  const workflowInput = {\n    workflowType: 'OrderFulfillment',\n    input: {\n      orderId: 'ord_9c4e1f',\n      customerId: 'cust_221a',\n      priority: 'express',\n      items: ['sku-100', 'sku-201', 'sku-303'],\n      shipTo: {\n        name: 'Alex Rivera',\n        address: '42 Elm St',\n        city: 'Springfield',\n        zip: '12345',\n      },\n    },\n    retryPolicy: {\n      maximumAttempts: 3,\n      initialInterval: '1s',\n      maximumInterval: '30s',\n      backoffCoefficient: 2,\n    },\n    searchAttributes: {\n      OrderStatus: 'pending',\n      CustomerId: 'cust_221a',\n    },\n  };\n</script>\n\n<PayloadInspector\n  value={workflowInput}\n  meta={{\n    contentType: 'application/json',\n    source: 'order-service',\n    timestamp: '2026-06-11T09:15:42Z',\n  }}\n/>\n"
+    }
+  ]
+}

package/src/components/payload-inspector/payload-inspector.svelte

@@ -0,0 +1,386 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category data-display
+   * @status beta
+   * @purpose Composed inspector for structured payloads with summary, tree, and raw views, copy actions, and size/truncation status.
+   * @tag json
+   * @tag inspector
+   * @tag payload
+   * @useWhen Inspecting workflow inputs, signal payloads, activity results, or API response bodies in a dashboard.
+   * @useWhen Displaying a structured payload with metadata like content type, source, and timestamp.
+   * @avoidWhen Rendering a raw code block only — use code-block directly instead.
+   * @avoidWhen Needing search, filtering, or virtualization over large collections — compose a custom viewer.
+   * @related json-viewer, code-block, description-list, copy-button
+   */
+  export type {
+    PayloadInspectorMeta,
+    PayloadInspectorProps,
+    PayloadInspectorView,
+  } from './payload-inspector.types.ts';
+</script>
+
+<script lang="ts">
+  import type { PayloadInspectorProps } from './payload-inspector.types.ts';
+  import type { DescriptionListItem } from '../description-list/description-list.types.ts';
+
+  import Badge from '../badge/badge.svelte';
+  import CodeBlock from '../code-block/code-block.svelte';
+  import CopyButton from '../copy-button/copy-button.svelte';
+  import DescriptionList from '../description-list/description-list.svelte';
+  import JsonViewer from '../json-viewer/json-viewer.svelte';
+  import Tabs from '../tabs/tabs.svelte';
+  import TabList from '../tab-list/tab-list.svelte';
+  import Tab from '../tab/tab.svelte';
+  import TabPanel from '../tab-panel/tab-panel.svelte';
+  import { classNames } from '../../utilities/class-names.ts';
+
+  let {
+    value,
+    truncated = false,
+    maxBytes = 1_048_576,
+    meta,
+    format,
+    parse,
+    activeView = $bindable('summary'),
+    label = 'Payload inspector',
+    class: className,
+    ...rest
+  }: PayloadInspectorProps = $props();
+
+  // --------------------------------------------------------------------------
+  // Parsing: when value is a string, attempt to parse it as JSON (or with the
+  // custom parser). On failure, mark as invalid so we can show an error state.
+  // --------------------------------------------------------------------------
+
+  type ParseResult = { ok: true; parsed: unknown } | { ok: false; error: string };
+
+  const parseResult = $derived.by((): ParseResult => {
+    if (typeof value !== 'string') {
+      return { ok: true, parsed: value };
+    }
+    // Empty string is treated as null/absent rather than an error.
+    if (value.trim() === '') {
+      return { ok: true, parsed: null };
+    }
+    try {
+      const parser = parse ?? JSON.parse;
+      return { ok: true, parsed: parser(value) };
+    } catch (error) {
+      return {
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  });
+
+  const parsedValue = $derived(parseResult.ok ? parseResult.parsed : undefined);
+
+  // --------------------------------------------------------------------------
+  // Serialized size — compute once from the canonical in-memory value so that
+  // size display and the oversize gate are consistent with each other.
+  // --------------------------------------------------------------------------
+
+  type SizeResult = { ok: true; bytes: number } | { ok: false };
+
+  const sizeResult = $derived.by((): SizeResult => {
+    if (!parseResult.ok) return { ok: false };
+    try {
+      const json = JSON.stringify(parsedValue);
+      if (typeof json !== 'string') return { ok: false };
+      return { ok: true, bytes: new Blob([json]).size };
+    } catch {
+      return { ok: false };
+    }
+  });
+
+  const byteLabel = $derived.by((): string => {
+    if (!sizeResult.ok) return 'Unknown size';
+    const bytes = sizeResult.bytes;
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  });
+
+  // --------------------------------------------------------------------------
+  // Formatted raw text for the raw view.
+  //
+  // `format` controls how the raw view *displays* the payload — it is a
+  // serializer (e.g. sorted keys, custom indentation) not a redaction hook.
+  // Redaction should happen upstream: pass the already-redacted object as
+  // `value` so every view (Summary, Tree, Raw) sees the redacted form.
+  // --------------------------------------------------------------------------
+
+  const rawText = $derived.by((): string => {
+    if (!parseResult.ok) {
+      // Show the original string if we have one (so the user can see what failed to parse).
+      return typeof value === 'string' ? value : '';
+    }
+    try {
+      const formatter = format ?? ((v: unknown) => JSON.stringify(v, null, 2));
+      return formatter(parsedValue) ?? '';
+    } catch {
+      return typeof value === 'string' ? value : '';
+    }
+  });
+
+  // True when the in-memory value cannot be round-tripped through JSON.stringify
+  // (e.g. circular references, BigInt). Only fires for non-string values that
+  // parsed successfully — string parse errors are handled by parseResult.ok.
+  const unserializable = $derived.by((): boolean => {
+    if (typeof value === 'string' || !parseResult.ok) return false;
+    try {
+      JSON.stringify(parsedValue);
+      return false;
+    } catch {
+      return true;
+    }
+  });
+
+  // --------------------------------------------------------------------------
+  // Summary metadata items for DescriptionList.
+  // --------------------------------------------------------------------------
+
+  const summaryItems = $derived.by((): DescriptionListItem[] => {
+    const items: DescriptionListItem[] = [];
+    items.push({ term: 'Size', definition: byteLabel });
+
+    if (meta?.contentType) {
+      items.push({ term: 'Content type', definition: meta.contentType });
+    }
+    if (meta?.source) {
+      items.push({ term: 'Source', definition: meta.source });
+    }
+    if (meta?.timestamp) {
+      // Attempt to format as a locale string; fall back to raw string.
+      let displayTime = meta.timestamp;
+      try {
+        displayTime = new Date(meta.timestamp).toLocaleString();
+      } catch {
+        // leave as-is
+      }
+      items.push({ term: 'Timestamp', definition: displayTime });
+    }
+    return items;
+  });
+
+  // --------------------------------------------------------------------------
+  // Type classification for the summary type badge.
+  // --------------------------------------------------------------------------
+
+  type ValueKind =
+    | 'null'
+    | 'undefined'
+    | 'boolean'
+    | 'number'
+    | 'string'
+    | 'array'
+    | 'object'
+    | 'invalid';
+
+  const valueKind = $derived.by((): ValueKind => {
+    if (!parseResult.ok) return 'invalid';
+    const v = parsedValue;
+    if (v === null) return 'null';
+    if (v === undefined) return 'undefined';
+    if (typeof v === 'boolean') return 'boolean';
+    if (typeof v === 'number') return 'number';
+    if (typeof v === 'string') return 'string';
+    if (Array.isArray(v)) return 'array';
+    return 'object';
+  });
+
+  // --------------------------------------------------------------------------
+  // Whether the value is a primitive (shown inline in the summary).
+  // --------------------------------------------------------------------------
+
+  const isPrimitive = $derived(
+    valueKind === 'null' ||
+      valueKind === 'undefined' ||
+      valueKind === 'boolean' ||
+      valueKind === 'number' ||
+      valueKind === 'string',
+  );
+
+  const isEmpty = $derived(parsedValue === undefined && value === undefined);
+
+  // --------------------------------------------------------------------------
+  // Copy targets for the header copy buttons.
+  //
+  // copy-raw  → "payload as received": the original string verbatim if value
+  //             was a string, otherwise compact JSON (one-liner, no spaces).
+  //             This is what you would paste into a message bus or log query.
+  //
+  // copy-formatted → pretty-printed JSON of the parsed value (2-space indent).
+  //                  Ignores the `format` prop so it is always valid JSON.
+  //                  This is what you would read or diff in an editor.
+  // --------------------------------------------------------------------------
+
+  const copyRawText = $derived.by((): string => {
+    if (typeof value === 'string') return value;
+    if (!parseResult.ok) return '';
+    try {
+      return JSON.stringify(parsedValue) ?? '';
+    } catch {
+      return '';
+    }
+  });
+
+  const copyFormattedText = $derived.by((): string => {
+    if (!parseResult.ok) return rawText;
+    try {
+      return JSON.stringify(parsedValue, null, 2) ?? '';
+    } catch {
+      return rawText;
+    }
+  });
+
+  const canCopyFormatted = $derived(!isEmpty && parseResult.ok && !unserializable);
+  const canCopyRaw = $derived(!isEmpty && (typeof value === 'string' || canCopyFormatted));
+
+  // --------------------------------------------------------------------------
+  // Helper: badge variant for the type tag.
+  // --------------------------------------------------------------------------
+
+  function kindVariant(kind: ValueKind): 'neutral' | 'info' | 'success' | 'warning' | 'danger' {
+    if (kind === 'invalid') return 'danger';
+    if (kind === 'null' || kind === 'undefined') return 'warning';
+    if (kind === 'object' || kind === 'array') return 'info';
+    return 'neutral';
+  }
+
+  // --------------------------------------------------------------------------
+  // Computed active view binding — keep activeView in sync with $bindable.
+  // Because Tabs uses bind:value internally, we forward the $bindable to it
+  // directly. The Tabs bind creates a two-way link that keeps activeView
+  // updated when the user switches tabs, and respects external changes too.
+  // --------------------------------------------------------------------------
+</script>
+
+<section {...rest} class={classNames('cinder-payload-inspector', className)} aria-label={label}>
+  <!-- Header bar: label, size, copy actions -->
+  <div class="cinder-payload-inspector__header">
+    <span class="cinder-payload-inspector__label">{label}</span>
+    <div class="cinder-payload-inspector__header-actions">
+      {#if sizeResult.ok}
+        <span class="cinder-payload-inspector__size" aria-label={`${byteLabel} payload size`}>
+          {byteLabel}
+        </span>
+      {/if}
+      {#if truncated}
+        <Badge variant="warning" size="xs">Truncated</Badge>
+      {/if}
+      {#if canCopyFormatted}
+        <CopyButton
+          value={copyFormattedText}
+          label="Copy formatted"
+          copiedLabel="Formatted copied"
+          iconOnly
+        />
+      {/if}
+      {#if canCopyRaw}
+        <CopyButton value={copyRawText} label="Copy raw" copiedLabel="Raw copied" iconOnly />
+      {/if}
+    </div>
+  </div>
+
+  <!-- Tab switcher: Summary / Tree / Raw -->
+  <div class="cinder-payload-inspector__tabs">
+    <Tabs bind:value={activeView}>
+      <TabList label="Inspector views">
+        <Tab value="summary">Summary</Tab>
+        <Tab value="tree">Tree</Tab>
+        <Tab value="raw">Raw</Tab>
+      </TabList>
+
+      <!-- Summary panel -->
+      <TabPanel value="summary">
+        <div class="cinder-payload-inspector__panel">
+          {#if isEmpty}
+            <div class="cinder-payload-inspector__empty" role="status">No payload</div>
+          {/if}
+          {#if !isEmpty}
+            <div class="cinder-payload-inspector__summary">
+              <div class="cinder-payload-inspector__summary-badges">
+                <Badge variant={kindVariant(valueKind)} size="xs" mono>{valueKind}</Badge>
+                {#if truncated}
+                  <Badge variant="warning" size="xs">Truncated</Badge>
+                {/if}
+              </div>
+              {#if summaryItems.length > 0}
+                <DescriptionList items={summaryItems} variant="two-column" />
+              {/if}
+              {#if !parseResult.ok}
+                <div
+                  class="cinder-payload-inspector__notice cinder-payload-inspector__notice--warning"
+                  role="alert"
+                >
+                  Parse error: {parseResult.error}
+                </div>
+              {/if}
+              {#if parseResult.ok && isPrimitive}
+                <div class="cinder-payload-inspector__summary-value">
+                  <span class="cinder-payload-inspector__summary-value-label">Value</span>
+                  <span class="cinder-payload-inspector__primitive">{String(parsedValue)}</span>
+                </div>
+              {/if}
+            </div>
+          {/if}
+        </div>
+      </TabPanel>
+
+      <!-- Tree panel -->
+      <TabPanel value="tree">
+        <div class="cinder-payload-inspector__panel">
+          {#if isEmpty}
+            <div class="cinder-payload-inspector__empty" role="status">No payload</div>
+          {/if}
+          {#if !isEmpty && !parseResult.ok}
+            <div
+              class="cinder-payload-inspector__notice cinder-payload-inspector__notice--warning"
+              role="alert"
+            >
+              Cannot render tree: {parseResult.error}
+            </div>
+          {/if}
+          {#if !isEmpty && parseResult.ok && unserializable}
+            <div class="cinder-payload-inspector__notice" role="status">
+              This value can't be serialized as JSON (it may contain circular references or BigInt
+              values).
+            </div>
+          {/if}
+          {#if !isEmpty && parseResult.ok && !unserializable}
+            <JsonViewer value={parsedValue} {maxBytes} />
+          {/if}
+        </div>
+      </TabPanel>
+
+      <!-- Raw panel -->
+      <TabPanel value="raw">
+        <div class="cinder-payload-inspector__panel cinder-payload-inspector__panel--code">
+          {#if isEmpty}
+            <div class="cinder-payload-inspector__empty" role="status">No payload</div>
+          {/if}
+          {#if !isEmpty && truncated}
+            <div class="cinder-payload-inspector__notice cinder-payload-inspector__notice--warning">
+              This payload has been truncated by the producer. The raw view shows only the received
+              portion.
+            </div>
+          {/if}
+          {#if !isEmpty && unserializable}
+            <div class="cinder-payload-inspector__notice" role="status">
+              This value can't be serialized as JSON (it may contain circular references or BigInt
+              values).
+            </div>
+          {/if}
+          {#if !isEmpty && !unserializable}
+            <!-- highlight={false} is an absolute off-switch: no Shiki import,
+                 guaranteed-escaped plaintext. Consumers who want highlighting can
+                 pass a `format` function and swap in a custom view. -->
+            <CodeBlock code={rawText} highlight={false} class="cinder-payload-inspector__raw" />
+          {/if}
+        </div>
+      </TabPanel>
+    </Tabs>
+  </div>
+</section>

package/src/components/payload-inspector/payload-inspector.types.ts

@@ -0,0 +1,72 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+/** Active view tab for the inspector. */
+export type PayloadInspectorView = 'summary' | 'tree' | 'raw';
+
+/**
+ * Structured metadata about the payload shown in the summary view.
+ */
+export type PayloadInspectorMeta = {
+  /** Content type or serializer label, e.g. "application/json" or "Protobuf". */
+  contentType?: string;
+  /** Optional source label, e.g. a workflow name, activity name, or endpoint path. */
+  source?: string;
+  /** Optional ISO 8601 timestamp string rendered in the summary. */
+  timestamp?: string;
+};
+
+/**
+ * Props for the PayloadInspector component.
+ */
+export type PayloadInspectorProps = Omit<HTMLAttributes<HTMLElement>, 'class' | 'children'> & {
+  /**
+   * The payload value to inspect. Pass any JSON-serializable value — object,
+   * array, string, number, boolean, or null. Pass a string for already-
+   * serialized JSON; the component will attempt to parse it. Pass `undefined`
+   * when no payload is available yet.
+   */
+  value?: unknown;
+  /**
+   * When true, the payload has been truncated by the producer (e.g. because it
+   * exceeded a wire size limit). The inspector renders a truncation badge in the
+   * summary and a notice above the raw view.
+   */
+  truncated?: boolean;
+  /**
+   * Maximum byte size before the tree view is replaced with an oversize
+   * placeholder. Defaults to 1,048,576 (1 MB). Does not affect the raw view.
+   */
+  maxBytes?: number;
+  /**
+   * Structured metadata shown in the summary panel. Pass contentType, source,
+   * and/or timestamp to populate the description list rows.
+   */
+  meta?: PayloadInspectorMeta;
+  /**
+   * Custom serializer for the Raw view display text. Receives the parsed value
+   * and must return a string. Defaults to JSON.stringify with 2-space
+   * indentation. Use this to customize key ordering, indentation, or
+   * alternative serialization formats. Does not affect the Summary or Tree
+   * views, or the copy buttons. For redaction, transform the value upstream and
+   * pass the already-redacted value as `value`.
+   */
+  format?: (value: unknown) => string;
+  /**
+   * Custom parser applied when `value` is a string. Receives the raw string
+   * and must return a parsed value or throw. Defaults to JSON.parse. Use this
+   * to support alternative serialization formats.
+   */
+  parse?: (raw: string) => unknown;
+  /**
+   * Initially active view tab. Defaults to "summary". Bind to control
+   * the active tab from outside.
+   */
+  activeView?: PayloadInspectorView;
+  /**
+   * Label for the inspector region, used as the accessible name for the
+   * containing section. Defaults to "Payload inspector".
+   */
+  label?: string;
+  /** Additional CSS classes applied to the root element. */
+  class?: string;
+};