Bindings and fragments - Asakiri Docs

Lessons and exercises are made of fragments. Each fragment binds to a piece of reusable content, a media asset, or an intentional inline literal. Bindings are how the outline connects to the content and media it displays.

Binding

type Binding =
  | { readonly kind: "record"; readonly recordId: string }
  | { readonly kind: "field"; readonly recordId: string; readonly fieldId: string }
  | { readonly kind: "item";  readonly recordId: string; readonly fieldId: string; readonly itemId: string }
  | { readonly kind: "asset"; readonly assetId: string }
  | { readonly kind: "literal"; readonly value: PortableValue };

Kind	Points at	Use it for
`record`	A whole record	Rendering a record with its presentation, or linking records
`field`	One field of a record	A single translation, reading, or the primary text
`item`	One item in a list field	A specific pronunciation, image, or example
`asset`	A media asset directly	Standalone audio or an image not owned by a record
`literal`	An inline value	Text that is intentionally not reused (see Detachment)

PortableValue

Literal values are limited to validated, JSON-compatible data. Binary data and absolute paths never appear inline.

type PortableValue =
  | string | number | boolean | null
  | readonly PortableValue[]
  | { readonly [key: string]: PortableValue };

Render fragments

A fragment pairs a binding with a role that says how it is used in its context.

interface RenderFragment {
  readonly id: string;
  readonly role: string;   // "primary", "supporting-text", "visual", "audio", "translation", ...
  readonly binding: Binding;
}

The same record can appear in many fragments with different roles: its Japanese text as the primary prompt, its audio as an audio fragment, its English as a translation.

Detachment

Turning a live reference into a literal creates an intentional snapshot in the lesson or exercise. Detaching text or structured content copies the value inline. Detaching a presentation from a record does not duplicate binary media: media stays referenced by asset ID unless the author imports a distinct file. See Reference lifecycle.