render

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package render: human-reading document projection (pinax-human-reading-api-v1 P03). Unlike the Agent view above, this builder keeps user-written code, paths and terminology intact; untrusted HTML stays inert text. Pages are bounded by UTF-8 text bytes and node counts, oversized blocks continue via stable fragments, and budgets are explicit instead of silent truncation.

Package render builds deterministic, bounded, renderer-independent note trees.

Index

Constants

View Source
const (
	ReaderPageMaxTextBytes = 256 * 1024
	ReaderPageMaxNodes     = 512
	ReaderSourceMaxBytes   = 8 * 1024 * 1024
	ReaderTotalMaxNodes    = 65536
	ReaderOutlinePageSize  = 512
)

Reader budget defaults mirror the frozen schema constants.

View Source
const SchemaVersion = "render.view.v1alpha1"

Variables

This section is empty.

Functions

func BoundPayload

func BoundPayload(payload any, dropped *int, truncated *bool) any

BoundPayload strips transport-private fields and bounds every nested collection.

func HTML

func HTML(v View) string

func LocateReaderAnchor

func LocateReaderAnchor(document ReaderDocument, anchor string) int

LocateReaderAnchor resolves an anchor to its top-level block index; -1 when unknown. The renderer never scans the whole document on its own.

func NoteURI

func NoteURI(id, revision string) string

func SafeID

func SafeID(value string) bool

func SafeText

func SafeText(value string) bool

func Text

func Text(v View) string

Types

type Badge

type Badge struct {
	ObjectID   string `json:"object_id"`
	Version    uint64 `json:"version"`
	Revision   string `json:"revision"`
	RenderedAt string `json:"rendered_at"`
}

type FenceResult

type FenceResult struct {
	Payload    any
	Truncated  bool
	ErrorCode  string
	NextAction string
}

type Inputs

type Inputs struct {
	Body      string
	Ref       Reference
	Display   string
	Badge     Badge
	Backlinks []Reference
	Resolve   func(target, label string) Reference
	Fences    map[string]func(string) FenceResult
}

type Node

type Node struct {
	Type       string     `json:"type"`
	Anchor     string     `json:"anchor"`
	Text       string     `json:"text,omitempty"`
	Ref        *Reference `json:"ref,omitempty"`
	Fence      string     `json:"fence,omitempty"`
	Payload    any        `json:"payload,omitempty"`
	ErrorCode  string     `json:"error_code,omitempty"`
	NextAction string     `json:"next_action,omitempty"`
	Children   []Node     `json:"children,omitempty"`
	Truncated  bool       `json:"truncated"`
}

type Panel

type Panel struct {
	Entities      []Reference `json:"entities"`
	Truncated     bool        `json:"truncated"`
	DroppedUnsafe int         `json:"dropped_unsafe"`
}

type ReaderBudgetError

type ReaderBudgetError struct {
	Code string // document_too_large | document_budget_exceeded
}

ReaderBudgetError distinguishes the two explicit failure modes.

func (*ReaderBudgetError) Error

func (e *ReaderBudgetError) Error() string

type ReaderDocument

type ReaderDocument struct {
	Blocks      []ReaderDocumentNode
	Outline     []ReaderOutlineEntry
	AnchorIndex map[string]int    // anchor -> top-level block index
	BlockRefs   map[string]string // explicit block ID -> existing anchor; empty means ambiguous
	NodeCount   int
	TextBytes   int
	Warnings    []string
}

ReaderDocument is the parsed, budget-checked full document.

func BuildReaderDocument

func BuildReaderDocument(body string) (ReaderDocument, error)

BuildReaderDocument parses body into bounded human-reading blocks with a stable outline. It never mutates or redacts user text: paths, code and terminology survive verbatim while consumers treat text as inert. BuildReaderDocument parses a note body with no fence handlers; fenced blocks without an owner handler stay inert code.

func BuildReaderDocumentWithFences

func BuildReaderDocumentWithFences(body string, fences map[string]func(string) FenceResult) (ReaderDocument, error)

BuildReaderDocumentWithFences parses with owner-registered read-only fence handlers. A fenced block whose language matches a handler produces a fence (or fence_failed) node with an independently bounded payload and explicit error fields; registered handlers never execute note code.

type ReaderDocumentNode

type ReaderDocumentNode struct {
	Type          string               `json:"type"`
	Anchor        string               `json:"anchor"`
	Text          string               `json:"text,omitempty"`
	Children      []ReaderDocumentNode `json:"children,omitempty"`
	Ref           string               `json:"ref,omitempty"`
	Language      string               `json:"language,omitempty"`
	Alt           string               `json:"alt,omitempty"`
	BlockAnchor   string               `json:"block_anchor,omitempty"`
	FragmentIndex int                  `json:"fragment_index,omitempty"`
	LastFragment  bool                 `json:"last_fragment,omitempty"`
	OriginalType  string               `json:"original_type,omitempty"`
	Header        []string             `json:"header,omitempty"`
	// Tokens records [start, end) byte ranges of indivisible inline tokens
	// (code spans) inside Text so pagination never splits them. Transport
	// only; never serialized.
	Tokens [][2]int `json:"-"`
	// Fence semantics (owner-registered read-only handlers): fence name,
	// bounded payload and failure diagnostics. Mirror the legacy Agent
	// contract; payloads are bounded via BoundPayload, never executed.
	Fence      string `json:"fence,omitempty"`
	Payload    any    `json:"payload,omitempty"`
	ErrorCode  string `json:"error_code,omitempty"`
	NextAction string `json:"next_action,omitempty"`
	// contains filtered or unexported fields
}

ReaderDocumentNode is the human-reading node shape; JSON tags match the pinax.reader.document_node.v1alpha1 machine schema.

type ReaderEmbedCandidate added in v0.3.1

type ReaderEmbedCandidate struct {
	Anchor string
	Raw    string
}

An unresolved syntactic candidate, not permission to read a target. Asset versus note identity, fragments and visibility belong to the app resolver.

type ReaderOutlineEntry

type ReaderOutlineEntry struct {
	Anchor string `json:"anchor"`
	Title  string `json:"title"`
	Level  int    `json:"level"`
}

ReaderOutlineEntry is one outline row.

func ReaderOutlinePage

func ReaderOutlinePage(document ReaderDocument, offset int) (entries []ReaderOutlineEntry, next int)

ReaderOutlinePage slices the outline with a stable cursor.

type ReaderPage

type ReaderPage struct {
	Nodes        []ReaderDocumentNode
	Next         *ReaderPagePosition
	Complete     bool
	ContentBytes int
	NodeCount    int
	Warnings     []string
}

ReaderPage is one bounded page of the document.

func PaginateReaderDocument

func PaginateReaderDocument(document ReaderDocument, position ReaderPagePosition) ReaderPage

PaginateReaderDocument assembles one bounded page starting at position. Budgets count UTF-8 bytes (headers, nested subtrees and inline refs included) and nodes. Content paginates CONTINUOUSLY: leaf blocks batch their inline refs across pages and then fragment their text; structural blocks (lists, quotes) slice their children, recursing into oversized children so in-budget content is never dropped. Drops happen only for a single ref exceeding a whole page budget, always with an explicit warning.

type ReaderPagePosition

type ReaderPagePosition struct {
	BlockIndex int
	// Path is the opaque intra-block resume position (nested child indices,
	// byte offset, ref index, fragment counter) produced by the previous
	// page; empty means "start of block".
	Path string
	// DroppedBlocks carries prior pages' explicit budget drops so the final
	// page can never claim completeness after content was dropped.
	DroppedBlocks int
}

ReaderPagePosition identifies the next page start: the top-level block index, and for mid-fragment blocks the exact byte offset plus the number of fragments already emitted for that block.

type ReaderRichAnnotation added in v0.3.1

type ReaderRichAnnotation struct {
	Anchor      string
	Kind        string // mermaid | math | callout
	Source      string
	CalloutKind string
	Title       string
	Fold        string // fixed | expanded | collapsed
}

Rich annotations are owner-internal semantics, not legacy reader wire fields. They never authorize HTML, network access, script execution or plugin calls.

type ReaderRichDocument added in v0.3.1

type ReaderRichDocument struct {
	Document    ReaderDocument
	Annotations []ReaderRichAnnotation
	Embeds      []ReaderEmbedCandidate
}

func BuildReaderRichDocument added in v0.3.1

func BuildReaderRichDocument(body string) (ReaderRichDocument, error)

BuildReaderRichDocument preserves the same text, nodes and anchors as the inert base builder. No fence-handler registry is accepted at this boundary.

type Reference

type Reference struct {
	Unsafe   bool   `json:"-"`
	URI      string `json:"uri,omitempty"`
	ObjectID string `json:"object_id,omitempty"`
	Title    string `json:"title,omitempty"`
	Version  uint64 `json:"version"`
	Revision string `json:"revision,omitempty"`
	Status   string `json:"status"`
	Mime     string `json:"mime,omitempty"`
}

type View

type View struct {
	SchemaVersion string           `json:"schema_version"`
	Ref           Reference        `json:"ref"`
	Display       string           `json:"display"`
	Tree          []Node           `json:"tree"`
	Panels        map[string]Panel `json:"panels"`
	Badge         Badge            `json:"badge"`
	Truncated     bool             `json:"truncated"`
	DroppedUnsafe int              `json:"dropped_unsafe"`
	Warnings      []string         `json:"warnings"`
}

func Build

func Build(in Inputs) View

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL