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
- func BoundPayload(payload any, dropped *int, truncated *bool) any
- func HTML(v View) string
- func LocateReaderAnchor(document ReaderDocument, anchor string) int
- func NoteURI(id, revision string) string
- func SafeID(value string) bool
- func SafeText(value string) bool
- func Text(v View) string
- type Badge
- type FenceResult
- type Inputs
- type Node
- type Panel
- type ReaderBudgetError
- type ReaderDocument
- type ReaderDocumentNode
- type ReaderEmbedCandidate
- type ReaderOutlineEntry
- type ReaderPage
- type ReaderPagePosition
- type ReaderRichAnnotation
- type ReaderRichDocument
- type Reference
- type View
Constants ¶
const ( ReaderPageMaxTextBytes = 256 * 1024 ReaderPageMaxNodes = 512 ReaderSourceMaxBytes = 8 * 1024 * 1024 ReaderTotalMaxNodes = 65536 ReaderOutlinePageSize = 512 )
Reader budget defaults mirror the frozen schema constants.
const SchemaVersion = "render.view.v1alpha1"
Variables ¶
This section is empty.
Functions ¶
func BoundPayload ¶
BoundPayload strips transport-private fields and bounds every nested collection.
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.
Types ¶
type 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 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
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"`
}