# signal:// A2V — Full Reference (v1.0.0)

A2V reconstructs video from ASCII / ANSI / asciicast / JSON-stream source text
and renders the same source into styled artifacts. This document is the complete
machine-readable reference for agents and automations.

## Architecture
- Browser studio: paste or upload ASCII/ANSI/multi-frame/asciicast/JSON/NDJSON
  text, apply animation effects, and record the canvas as video.
- Source handoff intake: trusted postMessage payloads from
  https://v2a.platphormnews.com, handoff/a2v/v2a URL payloads, A2V JSON stream
  files, and WebM artifact uploads.
- Source-quality path: when a handoff supplies the original WebM/source artifact, A2V
  plays and downloads that artifact directly instead of degrading it through an
  ASCII re-render. ASCII-only handoffs remain stylized reconstruction.
- Live V2A protocol: platphorm.v2a.a2v.handoff.v1. The receiver emits platphorm:a2v:ready, accepts nested frame.text and optional frame.colorGrid using rgb24-b64-v1, then emits platphorm:a2v:ack only after normalization. Untrusted origins and protocol mismatches are ignored.
- Frame intake (lib/frames.ts): strips ANSI escapes, splits delimiter-based
  multi-frame text, parses asciicast v2 recordings into frame snapshots, and
  parses JSON arrays / { frames: [...] } / NDJSON frame streams.
- Artifact exporters (lib/exporters.ts): render a selected frame to SVG, HTML,
  ANSI, JSON, JSON-stream NDJSON, or plain text with CRT color, glow, scanline,
  font-size, and gradient styling.
- HTTP API: stateless single-frame ASCII artifact rendering for scripts,
  automations, and AI agents.
- MCP server: exposes the same renderer as JSON-RPC 2.0 tooling.
- Observability: render and MCP tool calls accept W3C traceparent/tracestate plus allowlisted baggage, emit public-safe spans and evidence when PLATPHORM_API_KEY is configured, and return the trace ID and Trace URL in response headers.

## Input model
1. Raw ASCII text: one still frame.
2. ANSI / VT100 text: control sequences are stripped while printable glyphs are preserved.
3. Multi-frame text: delimiter lines (---, ===, ~~~, ###) and form feeds split frames.
4. asciicast v2: newline-delimited JSON is parsed into best-effort screen snapshots.
5. JSON stream: JSON arrays, { "frames": [...] } documents, or NDJSON frame objects become playback frames.
6. Remote ASCII URL: fetched as text and bounded by the same byte limit.
7. Trusted source/WebM artifact: browser-only source-quality playback/download.

## Endpoints

### GET /api/health
Returns service status, version, and capability flags.
https://a2v.platphormnews.com/api/health

### POST /api/v1/render
Render ASCII/asciicast/JSON-stream input. Supported input forms:
- multipart/form-data with an `ascii` file/text field
- JSON body { "ascii": "..." }
- JSON body { "asciiUrl": "https://..." }
- JSON body { "asciiBase64": "<base64 or data URL>" }
- raw text/plain body
Params may be given as query string, form fields, or JSON keys.
Max input: 2097152 bytes. Max measured grid: 1000 columns x 1000 rows.
Remote asciiUrl is restricted to trusted https domains and blocks private-network targets.
WebM/source-quality restoration is a browser handoff/upload path, not a stateless server render format.
Set format=json-stream to return one canonical A2V frame object per NDJSON line.

### POST /api/mcp
Model Context Protocol over JSON-RPC 2.0. Methods: initialize, ping, tools/list,
tools/call, resources/list, resources/read, prompts/list, and prompts/get. Tool:
render_ascii (returns text; set color/format for richer output).

### GET /api/openapi.json
OpenAPI 3.1 specification.

## Parameters

### format
- type: enum
- default: svg
- svg | html | ansi | json | json-stream | text output artifact.

### monoColor
- type: hex
- default: #22c55e
- Phosphor / glyph color.

### background
- type: hex
- default: #050805
- Backdrop color (svg/html).

### glow
- type: float 0–1
- default: 0.6
- CRT phosphor bloom amount (svg/html).

### scanlines
- type: boolean
- default: true
- Overlay CRT scanlines (svg/html).

### fontSize
- type: integer 6–48
- default: 14
- Cell height in px (svg/html).

### gradientTo
- type: hex | null
- default: null
- Optional top→bottom gradient target color.

### frame
- type: integer
- default: 0
- Frame index for multi-frame / .cast input.

### trim
- type: boolean
- default: true
- Trim blank border rows and columns.

## Output formats
- svg -> image/svg+xml (.svg): SVG (vector)
- html -> text/html (.html): HTML
- ansi -> text/plain (.ans): ANSI (truecolor)
- json -> application/json (.json): JSON
- json-stream -> application/x-ndjson (.ndjson): JSON stream (NDJSON)
- text -> text/plain (.txt): Plain text

## Defaults
{
  "format": "svg",
  "monoColor": "#22c55e",
  "background": "#050805",
  "glow": 0.6,
  "scanlines": true,
  "fontSize": 14,
  "gradientTo": null,
  "frame": 0,
  "trim": true
}

## Examples

# Plain text
curl -F "ascii=@frame.txt" "https://a2v.platphormnews.com/api/v1/render?format=text"

# 24-bit color ANSI (paste into a truecolor terminal)
curl -F "ascii=@frame.txt" "https://a2v.platphormnews.com/api/v1/render?format=ansi&monoColor=22c55e"

# Standalone HTML from JSON
curl -X POST https://a2v.platphormnews.com/api/v1/render \
  -H "Content-Type: application/json" \
  -d '{"ascii":"signal://a2v","format":"html","monoColor":"#22c55e","background":"#050805"}'

# JSON (one selected frame) for programmatic use
curl -X POST https://a2v.platphormnews.com/api/v1/render \
  -H "Content-Type: application/json" \
  -d '{"asciiBase64":"data:text/plain;base64,c2lnbmFsOi8vYTJ2","format":"json"}'

# JSON stream (all parsed frames as NDJSON)
curl -X POST https://a2v.platphormnews.com/api/v1/render \
  -H "Content-Type: application/json" \
  -d '{"ascii":"{\"frames\":[\"A2V frame 1\",\"A2V frame 2\"]}","format":"json-stream"}'

# MCP tool call
curl -X POST https://a2v.platphormnews.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"render_ascii","arguments":{"ascii":"signal://a2v","format":"ansi"}}}'