@astrolabe/core

Contracts and the i18n runtime. Every interface between the packages lives here; no runtime dependencies.

Classes

CheckerError

Thrown by checkers for protocol-level refusals, carrying the RFC 9457 problem document.

Extends

• Error

Constructors

Constructor

new CheckerError(problem): CheckerError;

Parameters

Parameter	Type
problem	ProblemDetails

Returns

CheckerError

Overrides

Error.constructor

Properties

Property	Modifier	Type
problem	readonly	ProblemDetails

---

MessageSyntaxError

Extends

• Error

Constructors

Constructor

new MessageSyntaxError(message, offset): MessageSyntaxError;

Parameters

Parameter	Type
message	string
offset	number

Returns

MessageSyntaxError

Overrides

Error.constructor

Properties

Property	Modifier	Type
offset	readonly	number

Interfaces

AnswerKey

Properties

Property	Modifier	Type	Description
format	readonly	1	-
groups	readonly	readonly ScoringGroup[]	-
lang	readonly	string	Content language of the document. Slots inherit it unless their key says otherwise.
pages	readonly	readonly string[]	View page ids in order.
slots	readonly	Readonly<Record<string, KeySlot>>	-
viewHash	readonly	string	View hash this key belongs to. Hosts must store and serve them together.

---

AttemptPolicy

Properties

Property	Modifier	Type	Description
deadline	readonly	string | null	ISO 8601. The server auto-submits at the deadline; the player only shows the countdown.
maxChecks	readonly	number | null	Practice only. null = unlimited.
mode	readonly	AttemptMode	practice: check any time. test: no check, one submit. review: read-only, shows a submitted attempt.
navigation	readonly	"free" | "linear"	linear: no going back to earlier pages (tests).
passMark	readonly	number | null	Fraction of the maximum score needed to pass, 0..1. null = no pass mark.
reveal	readonly	Reveal	-
seed	readonly	string | null	Seed for per-attempt UI shuffles. null = keep the view order.

---

AttributeSpec

Properties

Property	Modifier	Type	Description
default?	readonly	string | number | boolean	Value used when the attribute is absent. Documented and shown by the editor.
max?	readonly	number	-
min?	readonly	number	Inclusive bounds for integer and number.
name	readonly	string	-
required?	readonly	boolean	-
type	readonly	AttributeType	-
values?	readonly	readonly string[]	Allowed values for enum.
visibility	readonly	Visibility	-

---

CatalogProblem

Properties

Property	Modifier	Type
detail	readonly	string
key	readonly	string
kind	readonly	"missing" | "extra" | "syntax" | "params" | "plural"

---

ChangeDetail

Properties

Property	Modifier	Type	Description
answers	readonly	Answers	Changed slots only; '' = cleared.

---

Checker

Extended by

• LocalChecker

Methods

check()

check(request): Promise<CheckResponse>;

Practice only. Rejects with CheckerError (check_not_allowed) under other policies.

Parameters

Parameter	Type
request	CheckRequest

Returns

Promise<CheckResponse>

submit()

submit(request): Promise<SubmitResponse>;

Parameters

Parameter	Type
request	SubmitRequest

Returns

Promise<SubmitResponse>

---

CheckRequest

Properties

Property	Modifier	Type	Description
answers	readonly	Answers	-
page?	readonly	string	View page id: grade only that page. Omit to grade everything.

---

CheckResponse

Properties

Property	Modifier	Type	Description
checksLeft	readonly	number | null	Checks left in this attempt; null = unlimited.
result	readonly	GradeResult	-

---

ChildSpec

A child element type a component accepts, e.g. <astl-option> inside <astl-choice>.

• content: 'text': plain text only (e.g. an accepted alternative answer).
• content: 'inline': rich inline content (emphasis, lang spans, math).

Properties

Property	Modifier	Type	Description
attributes	readonly	readonly AttributeSpec[]	-
content	readonly	"text" | "inline"	-
max	readonly	number | null	null = unbounded.
min	readonly	number	-
tag	readonly	string	-
visibility	readonly	"public" | "private"	-

---

Compilation

Properties

Property	Modifier	Type	Description
key	readonly	AnswerKey	-
metadata	readonly	Metadata	-
view	readonly	string	-
viewHash	readonly	string	Lowercase hex SHA-256 of the UTF-8 view.

---

CompileContext

Properties

Property	Modifier	Type	Description
dir	readonly	Direction	-
lang	readonly	string	-
profile	readonly	NormalisationProfile	Engine-wide text comparison defaults; definitions apply their own attributes on top.

Methods

opaque()

opaque(localId?): string;

Opaque id for the current element (no argument) or for a source id local to it, e.g. an option id. Deterministic for (secret, salt, element id, local id), so recompiling gives the same view.

Parameters

Parameter	Type
localId?	string

Returns

string

opaqueOf()

opaqueOf(id, localId?): string;

The opaque id of another component (by source id) or of a source id local to it, as that component's view writes it: what a drop's view and key need of its word bank. Throws for an id validate did not check (no such component, or no such local id).

Parameters

Parameter	Type
id	string
localId?	string

Returns

string

permute()

permute<T>(items, options?): T[];

Keyed permutation, a pure function of (element seed, salt, item count): calling it twice gives the same order, so slots and toView agree. With avoidOriginal, 2+ items never come back in source order (use it when the source order is the answer, e.g. ordering tasks). Use different salts for independent permutations.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
items	readonly T[]
options?	{ avoidOriginal?: boolean; salt?: string; }
options.avoidOriginal?	boolean
options.salt?	string

Returns

T[]

---

CompileOptions

Properties

Property	Modifier	Type	Description
salt?	readonly	string	Mixed into opaque ids and permutations, e.g. the exercise id, so two exercises never share ids.

---

ComponentDefinition

Properties

Property	Modifier	Type	Description
manifest	readonly	ComponentManifest	-
messages?	readonly	readonly MessageCatalog[]	Catalogs of the manifest's namespace; the engine uses them to describe this type's issues.
migrations?	readonly	Readonly<Record<number, (element) => ElementNode>>	migrations[n] upgrades a source element written for version n to n + 1.

Methods

groups()?

optional groups(element, context):
  | readonly GroupSpec[]
  | null;

The scoring groups of an element graded in parts (a crossword's words): each scores by the rule of the element's scoring mode and gets its points, and together they hold every slot. Null or absent: one group, with the element's id, of all its slots. Called for valid graded elements only, after slots.

Parameters

Parameter	Type
element	ElementNode
context	CompileContext

Returns

| readonly GroupSpec[] | null

localIds()?

optional localIds(element): readonly string[];

Local ids of slots that no child stands for (a crossword's cells), read from the valid element. Each gets an opaque id as a child's id does: context.opaque(localId), fixture ref <id>/<localId>. Start them with a digit, so they never meet a child's id (source ids start with a letter). Absent: the children's ids only.

Parameters

Parameter	Type
element	ElementNode

Returns

readonly string[]

metadata()?

optional metadata(element): Readonly<Record<string, number>>;

Extra numbers for metadata (e.g. { words: 12 }), stored as <tag>.<name>.

Parameters

Parameter	Type
element	ElementNode

Returns

Readonly<Record<string, number>>

slots()

slots(element, context): readonly SlotSpec[];

Slots with their private keys, in reading order. Called only for valid elements.

Parameters

Parameter	Type
element	ElementNode
context	CompileContext

Returns

readonly SlotSpec[]

toView()

toView(element, context): ElementNode;

The public view element. Must not contain private attributes or private children; the engine enforces the manifest allow-list afterwards and fails the compile if a private value would leak.

Parameters

Parameter	Type
element	ElementNode
context	CompileContext

Returns

ElementNode

validate()

validate(element, context): void;

Type-specific checks on a sanitised element. The engine has already checked everything the manifest says (attribute types, enums, required attributes, child tags and counts, id).

Parameters

Parameter	Type
element	ElementNode
context	ValidateContext

Returns

void

---

ComponentManifest

Properties

Property	Modifier	Type	Description
a11y	readonly	object	Accessibility contract, used by docs and conformance: ARIA pattern and the keys that operate it.
a11y.keys	readonly	readonly string[]	-
a11y.pattern	readonly	string	-
attributes	readonly	readonly AttributeSpec[]	Type-specific attributes. The common ones (id, v, scoring, points) come from COMMON_ATTRIBUTES.
children	readonly	readonly ChildSpec[]	-
content?	readonly	"flow"	Absent: the element holds its declared children only. 'flow' (blocks only): it wraps rich content as a page holds it (paragraphs, headings, lists, quotes, figures, formatting, pictures; no components), and its declared children are inline children that sit in that content's text where an inline component may sit (a word to select in a passage); min and max count them wherever they are.
cssParts	readonly	readonly string[]	part names the element exposes for ::part() styling. Public theming API.
display	readonly	"inline" | "block"	inline sits inside text (a gap); block stands between paragraphs (a multiple choice).
graded	readonly	boolean	Whether the type is scored. Graded types form one scoring group of graded slots. Ungraded types have no scoring and add nothing to the maximum: they produce no slots (flash cards, media), or only open slots (a long answer), whose answers are stored with the attempt for a teacher.
issues	readonly	readonly string[]	Issue codes the definition may report (namespace = messages).
messages	readonly	string	i18n namespace for this type's messages, e.g. astl.gap.
scoring	readonly	ScoringSpec | null	null for ungraded types.
slotKinds	readonly	readonly string[]	Slot kinds the definition produces; each must be registered with the engine. Graded types list graded kinds only, ungraded types ungraded ones only (open).
tag	readonly	string	Custom element name. Built-ins use the astl- prefix; third parties use their own.
variants	readonly	VariantSpec | null	null for types with a single presentation.
version	readonly	number	Element format version, written as v="n" in views. Bump on incompatible changes and add a migration.

---

CreateI18nOptions

Properties

Property	Modifier	Type	Description
catalogs	readonly	readonly MessageCatalog[]	-
fallbackLocale?	readonly	string	Default en.
formatter?	readonly	MessageFormatter	-

---

EditorAdapter

What a WYSIWYG integration must provide so the authoring kit can drive it. Everything is in source HTML (the <astl-doc> format), so an adapter is free to use any internal model.

Extended by

• TextareaAdapter

Methods

getElement()

getElement(id): string | null;

Source HTML of one component element, or null when the id is not in the document.

Parameters

Parameter	Type
id	string

Returns

string | null

getSelection()

getSelection():
  | EditorSelection
  | null;

The component at the cursor, or null.

Returns

| EditorSelection | null

getSource()

getSource(): string;

The whole document as source HTML.

Returns

string

insert()

insert(html): void;

Inserts a source snippet (an instantiated template) at the cursor.

Parameters

Parameter	Type
html	string

Returns

void

onChange()

onChange(listener): () => void;

Subscribe to document changes. Returns an unsubscribe function.

Parameters

Parameter	Type
listener	() => void

Returns

() => void

onSelectionChange()

onSelectionChange(listener): () => void;

Subscribe to selection changes. Returns an unsubscribe function.

Parameters

Parameter	Type
listener	(selection) => void

Returns

() => void

replaceElement()

replaceElement(id, html): void;

Replaces one component element in place (inspector edits); the rest of the document is untouched.

Parameters

Parameter	Type
id	string
html	string

Returns

void

select()

select(id): void;

Moves the cursor to an element by source id (a component or a page) and focuses the editor.

Parameters

Parameter	Type
id	string

Returns

void

setSource()

setSource(source): void;

Replaces the whole document.

Parameters

Parameter	Type
source	string

Returns

void

wrap()?

optional wrap(tag): boolean;

Runs the wrap command of the type tag (EditorDescriptor.wrap) on the selection and focuses the editor; returns whether the document changed. Absent: the editor offers no such command.

Parameters

Parameter	Type
tag	string

Returns

boolean

---

EditorDescriptor

How authors create and edit one component type. Plain data, so it can also feed agent tools and docs. Message keys are looked up in the manifest's messages namespace.

Properties

Property	Modifier	Type	Description
companion?	readonly	object	The element this type works with, such as the word bank of a gap: an insert writes into an empty attribute the id of the first tag element of the inserted template (a starter that brings one), else of the document, and adds that tag's template at the end of the document when it has none.
companion.attribute	readonly	string	-
companion.tag	readonly	string	-
description	readonly	string	Message key of a one-line description for insert menus.
fields?	readonly	readonly InspectorField[]	Inspector fields. Absent = derived from the manifest by the authoring kit.
icon	readonly	string	Icon name in the host's icon set (Phosphor names recommended), e.g. text-t.
idPrefix	readonly	string	Prefix for generated ids: gap gives gap-1, gap-2, ...
label	readonly	string	Message key of the menu label, e.g. editor.label.
manifest	readonly	ComponentManifest	-
messages?	readonly	readonly MessageCatalog[]	Catalogs of the manifest's namespace (labels, help texts, template texts).
template	readonly	string	Source HTML that insert menus add. Placeholders: {{id}} = a fresh unique id, {{t:key}} = a message from the manifest's namespace in the author's UI locale (escaped). Local child ids (option ids) stay as written.
templates?	readonly	readonly EditorTemplate[]	Named starters: whole exercises with sample content, listed apart from the default template (which stays what the type's own entry inserts).
wrap?	readonly	EditorWrap	A command on the author's selection, for a type that holds rich content (content: 'flow').

---

EditorSelection

The component the cursor is in, by source id.

Properties

Property	Modifier	Type
id	readonly	string
tag	readonly	string

---

EditorTemplate

A named starter of a type, inserted like its default template.

Properties

Property	Modifier	Type	Description
description?	readonly	string	Message key of a one-line description.
icon?	readonly	string	Icon name; default: the descriptor's.
id	readonly	string	Kebab-case, unique among the descriptor's templates, e.g. two-gaps.
label	readonly	string	Message key of the menu label.
template	readonly	string	Source HTML with the placeholders of EditorDescriptor.template (one {{id}}, texts as {{t:key}}). Other components in it (the gaps of a word bank) are written without an id: each insert gives them fresh ones.

---

EditorWrap

Wraps the selected words in an inline child (Mark word): the editor puts each selected word in a new child element (a fresh local id, attributes as given) and the blocks around them in an element of this type when they are in none (with a fresh id, joined to one right before or after); on words already in the child it removes the child, keeping the text. Editors offer it as a button labelled label (EditorAdapter.wrap).

Properties

Property	Modifier	Type	Description
attributes?	readonly	Readonly<Record<string, string>>	Attributes of a new child besides its id, e.g. { correct: '' } for a boolean.
child	readonly	string	The inline child tag, one of the manifest's children.
label	readonly	string	Message key of the button label.

---

ElementContext

What the player gives each element when it mounts the view.

Properties

Property	Modifier	Type	Description
locale	readonly	string	UI locale for labels and announcements (not the content language).
number	readonly	number	1-based position among numbered elements (inline questions), for labels such as "Gap 3". 0 = not numbered.
seed	readonly	string | null	Per-attempt seed for UI shuffles; null = keep the view order.

Methods

announce()

announce(message): void;

Polite announcement through the player's single live region.

Parameters

Parameter	Type
message	string

Returns

void

t()

t(key, params?): string;

Formats a message in the UI locale from the element type's namespace, falling back to the shared astl.player namespace (verdict words such as verdict.correct, generic labels).

Parameters

Parameter	Type
key	string
params?	Readonly<Record<string, string | number>>

Returns

string

---

ElementFeedback

Properties

Property	Modifier	Type	Description
group	readonly	GroupVerdict | null	Verdict of the element's scoring group; null when ungraded or graded in parts.
groups?	readonly	Readonly<Record<string, GroupVerdict>>	Verdicts of the groups an element graded in parts names in groupIds (a crossword's words), by group id.
slots	readonly	Readonly<Record<SlotId, SlotVerdict>>	Verdicts for this element's slots that the student may see.

---

ElementNode

The document tree the engine and component definitions work on. Produced by the engine's HTML parser (sources) and serialised back to HTML (views). Plain data: no DOM, no parent pointers.

Properties

Property	Modifier	Type	Description
attrs	readonly	Readonly<Record<string, string>>	Attributes in source order. Values are already entity-decoded.
children	readonly	readonly Node[]	-
tag	readonly	string	Lowercase tag name, e.g. p, astl-gap.
type	readonly	"element"	-

---

Engine

Properties

Property	Modifier	Type	Description
manifests	readonly	readonly ComponentManifest[]	Manifests of the registered components, in registration order.

Methods

compile()

compile(source, options?): Promise<CompileResult>;

Parameters

Parameter	Type
source	string
options?	CompileOptions

Returns

Promise<CompileResult>

describe()

describe(issue, locale): string;

Renders an issue in the given UI locale (falls back to English, then to the code).

Parameters

Parameter	Type
issue	Issue
locale	string

Returns

string

grade()

grade(
   key,
   answers,
   options?
): GradeResult;

Pure and synchronous: safe to call per request. Malformed answers count as unanswered.

Parameters

Parameter	Type
key	AnswerKey
answers	Answers
options?	GradeOptions

Returns

GradeResult

solution()

solution(key, options?): Solution;

Parameters

Parameter	Type
key	AnswerKey
options?	GradeOptions

Returns

Solution

validate()

validate(source): ValidationReport;

Parameters

Parameter	Type
source	string

Returns

ValidationReport

---

EngineOptions

Properties

Property	Modifier	Type	Description
catalogs?	readonly	readonly MessageCatalog[]	Extra or replacement message catalogs (e.g. more locales) for describe.
components	readonly	readonly ComponentDefinition[]	-
profile?	readonly	Partial<NormalisationProfile>	Overrides of the default text comparison profile.
secret?	readonly	string | Uint8Array<ArrayBufferLike>	HMAC secret for opaque ids and permutations, at least 16 bytes. Keep it stable: it decides every view. Only compile needs it and throws without one. There is no default: a known secret undoes the keyed option order.
slotKinds?	readonly	readonly SlotKind<JsonObject>[]	Added to the built-in slot kinds (text, number, choice, flag). Same kind twice = error.
styleTemplates?	readonly	readonly StyleTemplate[]	Style templates the hosts' players register, so style-template values can be checked: a name that is not registered, or not allowed at its scope or for its tag, gives the warning STYLE_TEMPLATE_UNKNOWN (the attribute stays in the view). Same name twice = error.
urlPolicy?	readonly	UrlPolicy	Which URLs stay in sources and views (UrlPolicy). Default isSafeUrl.

---

ErrorDetail

Properties

Property	Modifier	Type
code	readonly	string
message	readonly	string

---

GradeContext

Properties

Property	Modifier	Type	Description
lang	readonly	string	Content language of the slot (BCP 47), for locale-aware comparisons.

---

GradeOptions

Properties

Property	Modifier	Type	Description
page?	readonly	string	Grade one view page only (per-page check).

---

GradeResult

Extends

• Score

Properties

Property	Modifier	Type	Description
correct	readonly	boolean	True when every included group is correct; false when no group is included (empty key or unknown page).
counts	readonly	VerdictCounts	Counts over groups.
groups	readonly	readonly GroupResult[]	-
max	readonly	number	-
pages	readonly	Readonly<Record<string, Score>>	Score per view page id.
score	readonly	number	-
slots	readonly	Readonly<Record<SlotId, SlotVerdict>>	Per-slot verdicts the student may see: answered slots only, selected flags only, and nothing for slots of multi-slot all-correct groups (those show only the group verdict).

---

GroupResult

Properties

Property	Modifier	Type
id	readonly	string
max	readonly	number
score	readonly	number
verdict	readonly	GroupVerdict

---

GroupSpec

A scoring group of an element graded in parts (see ComponentDefinition.groups).

Properties

Property	Modifier	Type	Description
id	readonly	string	Opaque group id, from context.opaque(localId): never the element's own id or one of its slot ids.
slots	readonly	readonly string[]	Some of the element's slot ids, in reading order. A slot may sit in several groups (a crossword's crossing).

---

I18n

Properties

Property	Modifier	Type
fallbackLocale	readonly	string

Methods

locales()

locales(namespace?): readonly string[];

Locales that have at least one catalog (for a namespace, if given).

Parameters

Parameter	Type
namespace?	string

Returns

readonly string[]

t()

t(
   locale,
   namespace,
   key,
   params?
): string;

Formats namespace:key in the best matching locale, then the fallback locale, else returns the key.

Parameters

Parameter	Type
locale	string
namespace	string
key	string
params?	Readonly<Record<string, string | number>>

Returns

string

translator()

translator(locale, namespace): Translate;

A translate function bound to one locale and namespace.

Parameters

Parameter	Type
locale	string
namespace	string

Returns

Translate

with()

with(catalogs): I18n;

A new instance with more catalogs. Later catalogs override earlier keys of the same namespace and locale.

Parameters

Parameter	Type
catalogs	readonly MessageCatalog[]

Returns

I18n

---

Issue

Properties

Property	Modifier	Type	Description
at	readonly	IssueLocation	-
code	readonly	string	Stable UPPER_SNAKE code. Component codes start with the type, e.g. CHOICE_CORRECT_MISSING.
namespace	readonly	string	i18n namespace of the message (astl.engine or the manifest's messages).
params	readonly	IssueParams	-
severity	readonly	Severity	Errors block compiling; warnings do not.

---

IssueLocation

Properties

Property	Modifier	Type	Description
element	readonly	string | null	Source id of the closest element that has one (the component), or null.
page	readonly	string | null	Source id of the page, or null for the implicit page / document level.
path	readonly	string	Readable path from the root, e.g. astl-doc > astl-page#p1 > p[2] > astl-gap#g1. Empty for issues raised before the document could be parsed (SOURCE_TOO_LARGE, DOC_ROOT_INVALID), whose tag is null.
tag	readonly	string | null	Tag of the element the issue is about, or null for the document.

---

JsonObject

Indexable

[key: string]: JsonValue

---

KeySlot

Properties

Property	Modifier	Type	Description
group	readonly	string	Opaque id of the component the slot belongs to, which is also the id of its scoring group, unless the component is graded in parts (ComponentDefinition.groups): then its groups list the slot. Open slots (an ungraded kind) belong to no group: no groups entry has this id or lists them.
key	readonly	JsonObject	-
kind	readonly	string	-
page	readonly	string	View page id.

---

MessageCatalog

Messages of one namespace in one locale. Values are ICU MessageFormat 1 strings.

Properties

Property	Modifier	Type	Description
locale	readonly	string	BCP 47, e.g. pl.
messages	readonly	Readonly<Record<string, string>>	-
namespace	readonly	string	e.g. astl.player, astl.gap.

---

MessageFormatter

Port for message formatting. The default is the ICU MessageFormat 1 subset in format.ts.

Methods

format()

format(
   message,
   params,
   locale
): string;

Parameters

Parameter	Type
message	string
params	MessageParams
locale	string

Returns

string

---

Metadata

Properties

Property	Modifier	Type	Description
dir	readonly	"ltr" | "rtl"	-
elements	readonly	Readonly<Record<string, number>>	Element counts by tag, e.g. { "astl-gap": 5 }.
extra	readonly	Readonly<Record<string, number>>	Numbers contributed by component metadata hooks, keyed tag.name.
format	readonly	number	-
groups	readonly	number	-
lang	readonly	string	-
maxScore	readonly	number	-
open	readonly	readonly string[]	Ids of the open slots (stored for a teacher, never graded), in reading order, so a server or a teacher's view can pick these answers out of a submission. They add nothing to maxScore.
pages	readonly	readonly PageMetadata[]	-
slots	readonly	number	Answer slots, open ones included: what a player's astl-ready counts.
viewHash	readonly	string	-
words	readonly	number	Words of running text, for reading-time estimates.

---

NormalisationProfile

How typed text is compared. Resolved at compile time and stored inside each text key, so stored keys grade the same forever, whatever the defaults are later.

Properties

Property	Modifier	Type	Description
case	readonly	"sensitive" | "insensitive"	insensitive: locale-aware lower-casing with the content language (Turkish dotless i works).
form	readonly	"NFC" | "NFKC"	Unicode normalisation applied first.
marks	readonly	"strict" | "fold"	fold: ignore diacritics (ą = a, ł = l, ø = o, ß = ss). strict keeps them: żółw != zolw.
punctuation	readonly	"strict" | "ignore-edge"	ignore-edge: drop punctuation at the start and end ("ssak." = "ssak").
quotes	readonly	"strict" | "fold"	fold: typographic quotes, apostrophes and dashes compare equal to ASCII ones.
space	readonly	"strict" | "collapse"	collapse: trim and turn every whitespace run into one space.

---

PageDetail

Properties

Property	Modifier	Type	Description
count	readonly	number	-
id	readonly	string	View page id.
index	readonly	number	-

---

PageMetadata

Properties

Property	Modifier	Type	Description
id	readonly	string	View page id.
label	readonly	string | null	-
maxScore	readonly	number	-
slots	readonly	number	Answer slots on the page, open ones included.

---

PlayerElementApi

Properties

Property	Modifier	Type	Description
disabled	public	boolean	-
feedback	public	| ElementFeedback | null	Shows verdicts; null clears them. Editing a slot clears its own verdict.
groupIds?	readonly	readonly string[]	The ids of the groups an element may be graded in (ComponentDefinition.groups), as its view names them: the player passes their verdicts in feedback.groups. Absent: one group, the element's id.
slotIds	readonly	readonly string[]	Slot ids this element answers, in reading order. Stable after the element connects.
solution	public	Readonly<Record<string, string>> | null	Shows the correct answers next to the student's; null hides them.

Methods

attach()

attach(context): void;

Called by the player once, before the first render. Elements must work with a default context too.

Parameters

Parameter	Type
context	ElementContext

Returns

void

getAnswers()

getAnswers(): Answers;

Answered slots only.

Returns

Answers

getUiState()?

optional getUiState(): JsonValue;

Non-answer UI state worth restoring after a reload.

Returns

JsonValue

setAnswers()

setAnswers(answers): void;

Unknown ids are ignored; '' clears a slot. Does not fire a change event.

Parameters

Parameter	Type
answers	Answers

Returns

void

setUiState()?

optional setUiState(state): void;

Parameters

Parameter	Type
state	JsonValue

Returns

void

units()

units(): Units;

Progress units, e.g. 3 of 5 cards placed.

Returns

Units

---

ProblemDetails

Properties

Property	Modifier	Type
code	readonly	ProblemCodeValue
detail?	readonly	string
status	readonly	number
title	readonly	string
type	readonly	string

---

ReadyDetail

Detail of astl-ready.

Properties

Property	Modifier	Type	Description
pages	readonly	number	Number of pages.
slots	readonly	number	Number of slots across all registered elements.
viewHash	readonly	string	-

---

Score

Extended by

• GradeResult

Properties

Property	Modifier	Type
max	readonly	number
score	readonly	number

---

ScoringGroup

Properties

Property	Modifier	Type	Description
id	readonly	string	-
page	readonly	string	View page id the group belongs to.
points	readonly	number	-
rule	readonly	ScoringRule	-
slots	readonly	readonly string[]	Slot ids in reading order.

---

ScoringSpec

Scoring modes an author can pick with the scoring attribute, each mapped to one engine rule. Mode names speak the author's language (all, per-option); rules are the three engine rules.

Properties

Property	Modifier	Type
default	readonly	string
modes	readonly	Readonly<Record<string, ScoringRule>>

---

SlotKind

Type Parameters

Type Parameter	Default type
TKey extends JsonObject	JsonObject

Properties

Property	Modifier	Type	Description
graded?	readonly	boolean	False for a kind that is stored but never graded (the built-in open): its slots belong to no scoring group, get no verdict and add nothing to the maximum, and only ungraded types (graded: false) produce them. Default true: graded types produce only graded kinds.
kind	readonly	string	-
selection	readonly	boolean	Selection slots use flag semantics (see scoring.ts).

Methods

isCorrect()

isCorrect(
   key,
   answer,
   context
): boolean;

answer is never empty here: the engine handles unanswered slots before calling.

Parameters

Parameter	Type
key	TKey
answer	string
context	GradeContext

Returns

boolean

isKey()

isKey(key): key is TKey;

Validates a stored key (compile output, or a key loaded from storage).

Parameters

Parameter	Type
key	JsonObject

Returns

key is TKey

solution()

solution(key): string;

The answer that shows the solution. '' = leave the slot empty (an unselected flag).

Parameters

Parameter	Type
key	TKey

Returns

string

---

SlotSpec

One graded unit produced by an element. key must satisfy the registered SlotKind's isKey.

Properties

Property	Modifier	Type	Description
id	readonly	string	Opaque slot id, from context.opaque(...).
key	readonly	JsonObject	-
kind	readonly	string	-

---

Snapshot

Properties

Property	Modifier	Type	Description
answers	readonly	Answers	-
checks	readonly	number	-
format	readonly	1	-
page	readonly	number	0-based page index.
savedAt	readonly	string	ISO 8601.
submitted	readonly	boolean	-
ui	readonly	Readonly<Record<string, JsonValue>>	Non-answer UI state per element id (e.g. a flashcard index).
viewHash	readonly	string | null	View the snapshot was taken on. A player ignores snapshots of another view.

---

StateDetail

Properties

Property	Modifier	Type
previous	readonly	AttemptState
state	readonly	AttemptState

---

StyleTemplate

Properties

Property	Modifier	Type	Description
catalogs?	readonly	readonly MessageCatalog[]	Catalogs of that namespace.
components?	readonly	readonly string[]	Component tags it supports at the component scope; absent = every registered component.
dark?	readonly	Readonly<Record<string, string>>	Overrides on top of tokens for the dark theme only.
light?	readonly	Readonly<Record<string, string>>	Overrides on top of tokens for the light theme only.
messages	readonly	string	i18n namespace of its texts: label (picker label) and description (one line), e.g. astl.style.notebook.
name	readonly	string	What authors write in style-template. Matches STYLE_TEMPLATE_NAME.
parts?	readonly	Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, string>>>>>>	::part() declarations by component tag, then part name (a name from the manifest's cssParts), e.g. { 'astl-choice': { option: { 'border-radius': 'var(--astl-radius-l)' } } }. Use tokens in values so the declarations follow the theme.
scopes	readonly	readonly StyleScope[]	Where the template may be used.
tokens?	readonly	Readonly<Record<string, string>>	Token overrides for the light and dark themes (never hc).
version	readonly	number	Bumped when the look changes visibly. Exercises keep referring to the name.

---

SubmitRequest

Properties

Property	Modifier	Type
answers	readonly	Answers

---

SubmitResponse

Properties

Property	Modifier	Type	Description
passed	readonly	boolean | null	null when there is no pass mark or nothing is revealed.
result	readonly	GradeResult | null	null when the policy reveals nothing yet.
solution	readonly	Readonly<Record<string, string>> | null	Only when the policy reveals answers.
submittedAt	readonly	string	ISO 8601, set by whoever grades.

---

TextNode

Properties

Property	Modifier	Type
type	readonly	"text"
value	readonly	string

---

Units

Properties

Property	Modifier	Type
answered	readonly	number
total	readonly	number

---

ValidateContext

Properties

Property	Modifier	Type	Description
lang	readonly	string	Content language at this element (nearest lang, else the document's).
profile	readonly	NormalisationProfile	Engine-wide text comparison defaults (for duplicate checks); definitions apply their own attributes on top.

Methods

find()

find(id): ElementNode | undefined;

Another component on the same page, by source id, sanitised as its own definition sees it (a drop names its word bank); undefined when the page has none. Pages are played one at a time, so elements that work together share a page. Definitions run once the whole document is read, so the element may come later in the source.

Parameters

Parameter	Type
id	string

Returns

ElementNode | undefined

report()

report(
   code,
   params?,
   options?
): void;

Reports an issue on the current element, or on one of its children (for a precise path). code must be listed in the manifest's issues. Default severity: error.

Parameters

Parameter	Type
code	string
params?	Readonly<Record<string, string | number>>
options?	{ child?: ElementNode; severity?: Severity; }
options.child?	ElementNode
options.severity?	Severity

Returns

void

---

ValidationReport

Properties

Property	Modifier	Type	Description
issues	readonly	readonly Issue[]	-
ok	readonly	boolean	True when there are no errors (warnings allowed).

---

VariantSpec

Presentation variants, picked by authors with the public variant attribute: how the element looks and behaves for the student (a gap that grows while typing, a select with a search box), never what it grades or which answers exist, so every variant of a source grades the same. The engine validates the value (an enum of values), elements render it, the authoring kit offers it (labels: editor.value.variant.<value> in the manifest's namespace). Adding a variant is not a breaking change; removing one or changing the default is (bump version).

Properties

Property	Modifier	Type	Description
default	readonly	string	Used when the attribute is absent or unknown to an older player.
values	readonly	readonly string[]	Kebab-case names, default included.

---

VerdictCounts

Properties

Property	Modifier	Type	Description
correct	readonly	number	-
empty	readonly	number	-
incorrect	readonly	number	-
partial	readonly	number	-
total	readonly	number	Number of groups counted.

Type Aliases

Answers

type Answers = Readonly<Record<SlotId, string>>;

---

AttemptMode

type AttemptMode = "practice" | "test" | "review";

Attempt policies. Practice, quiz and test are policies over the same content, not different content kinds. The server is authoritative: the player only reflects the policy it is given.

---

AttemptState

type AttemptState =
  | "loading"
  | "ready"
  | "active"
  | "checking"
  | "submitting"
  | "submitted"
  | "review"
  | "error";

---

AttributeType

type AttributeType = "string" | "boolean" | "integer" | "number" | "enum" | "id" | "url";

• id: a source id local to the component (e.g. an option id); replaced by an opaque id in the view.
• boolean: HTML boolean attribute (present = true; "false" is invalid).
• url: checked by the engine's UrlPolicy; a blocked URL is removed with a URL_BLOCKED warning.

---

CompileResult

type CompileResult =
  | object & Compilation
  | {
  issues: readonly Issue[];
  ok: false;
};

---

Declarations

type Declarations = Readonly<Record<string, string>>;

CSS declarations by property name, e.g. { 'border-radius': 'var(--astl-radius-l)' }.

---

Direction

type Direction = "ltr" | "rtl";

---

EngineIssueCode

type EngineIssueCode = typeof EngineIssue[keyof typeof EngineIssue];

---

GroupVerdict

type GroupVerdict = "correct" | "partial" | "incorrect" | "empty";

---

InspectorField

type InspectorField =
  | {
  accept?: string;
  help?: string;
  kind: "attribute";
  label: string;
  name: string;
  options?: {
     from: string;
     tag: string;
  };
}
  | {
  help?: string;
  kind: "text-list";
  label: string;
  multiline?: boolean;
  tag: string;
}
  | {
  attribute: string;
  help?: string;
  kind: "child-flag" | "child-text";
  label: string;
  tag: string;
}
  | {
  attribute: string;
  help?: string;
  kind: "child-choice";
  label: string;
  options?: string;
  tag: string;
}
  | {
  columns: readonly object[];
  help?: string;
  kind: "child-table";
  label: string;
  tag: string;
}
  | {
  help?: string;
  kind: "picture-regions" | "picture-points";
  label: string;
  src: string;
  tag: string;
};

One inspector control:

• attribute: an attribute of the element (control picked from the AttributeSpec type);
• text-list: repeated private text children (e.g. accepted alternatives <astl-alt>);
• child-flag: a boolean attribute on each child of a tag, listed by the child's text (e.g. which options are correct); its label and help messages get count (children) and checked (children with the flag);
• child-text: a free-text attribute on each child of a tag, listed by the child's text (e.g. the word each clue hides); an empty value removes the attribute;
• child-choice: one value of an attribute on each child of a tag, listed by the child's text: one of the attribute's enum values (e.g. whether each statement is true or false), or with options, the id of a child of another tag (e.g. the category of each card).
• child-table: the children of a tag as rows, each listed by its text, with a control for each of columns (by the attribute's type: text, number or a select of its enum values) and a button that removes it; a button adds a row, a child with a fresh local id and a first value for each required attribute (e.g. a crossword's words).
• picture-regions: zones on the element's picture, one child of tag each, drawn with a pointer or typed in number fields. A zone has id (local), shape (rect, circle or polygon), x and y (rect: its top-left corner; circle: its centre), width and height (rect), r (circle, a share of the width), points (polygon: x,y x,y ...) and an optional label. Every coordinate is a percentage of the picture, which never mirrors: x of its width from the left edge, y of its height from the top.
• picture-points: pins on the picture, one child of tag each: id, x and y (percent) and label. Both show the picture of the element's url attribute src, which they set by upload or address. Rich content (prompts, option texts) is edited in the WYSIWYG itself. The children of a tag are found anywhere in the element, so the inline children of a type with rich content (content: 'flow') are listed too.

Union Members

Type Literal

{
  accept?: string;
  help?: string;
  kind: "attribute";
  label: string;
  name: string;
  options?: {
     from: string;
     tag: string;
  };
}

Name	Type	Description
accept?	string	A url attribute: the files an author may upload for it with the host's uploadAsset (a file input's accept, e.g. video/mp4,video/webm). Absent, or without an upload, the address is typed.
help?	string	Message key of help text, optional.
kind	"attribute"	-
label	string	Message key of the label.
name	string	Attribute name, e.g. answer.
options?	object	Choices from another element of the document, in a select: the ids of the tag children of the element whose id is in this element's attribute from, listed by their text (e.g. the words of the bank a drop takes its words from). Without the document or that element, the attribute's own control.
options.from	string	-
options.tag	string	-

---

Type Literal

{
  help?: string;
  kind: "text-list";
  label: string;
  multiline?: boolean;
  tag: string;
}

Name	Type	Description
help?	string	-
kind	"text-list"	-
label	string	-
multiline?	boolean	Each child in a text area that keeps its line breaks (a transcript), not on one line.
tag	string	Child tag, e.g. astl-alt.

---

Type Literal

{
  attribute: string;
  help?: string;
  kind: "child-flag" | "child-text";
  label: string;
  tag: string;
}

Name	Type	Description
attribute	string	Attribute on each child: a boolean for child-flag (e.g. correct), a string for child-text.
help?	string	-
kind	"child-flag" | "child-text"	-
label	string	-
tag	string	Child tag, e.g. astl-option.

---

Type Literal

{
  attribute: string;
  help?: string;
  kind: "child-choice";
  label: string;
  options?: string;
  tag: string;
}

Name	Type	Description
attribute	string	Attribute on each child, e.g. answer or category.
help?	string	-
kind	"child-choice"	-
label	string	-
options?	string	Where the choices come from. Absent: the attribute's enum values (editor.value.<attribute>.<value>, e.g. true / false of each statement). A child tag: the ids of the element's children with that tag, listed by their text (e.g. astl-category for the category of each card).
tag	string	Child tag, e.g. astl-statement or astl-card.

---

Type Literal

{
  columns: readonly object[];
  help?: string;
  kind: "child-table";
  label: string;
  tag: string;
}

Name	Type	Description
columns	readonly object[]	The child's attributes edited in each row, in order, each with the message key of its label.
help?	string	-
kind	"child-table"	-
label	string	-
tag	string	Child tag, e.g. astl-crossword-word.

---

Type Literal

{
  help?: string;
  kind: "picture-regions" | "picture-points";
  label: string;
  src: string;
  tag: string;
}

Name	Type	Description
help?	string	-
kind	"picture-regions" | "picture-points"	-
label	string	-
src	string	The element's url attribute that holds the picture, e.g. src.
tag	string	Child tag of a zone or a pin, e.g. astl-region.

---

IssueParams

type IssueParams = Readonly<Record<string, string | number>>;

---

JsonArray

type JsonArray = readonly JsonValue[];

---

JsonValue

type JsonValue =
  | string
  | number
  | boolean
  | null
  | JsonArray
  | JsonObject;

A JSON value. Every contract object that crosses a process boundary is made of these.

---

MessageParams

type MessageParams = Readonly<Record<string, string | number>>;

i18n contracts. Two axes are kept apart everywhere:

• UI locale: chrome, labels, issue messages, announcements (the reader's choice);
• content language: the lang of the exercise text, used for grading and rendering (the author's choice).

---

MessagePart

type MessagePart =
  | {
  type: "text";
  value: string;
}
  | {
  name: string;
  style: "plain" | "number" | "integer" | "percent";
  type: "arg";
}
  | {
  name: string;
  offset: number;
  options: Readonly<Record<string, readonly MessagePart[]>>;
  ordinal: boolean;
  type: "plural";
}
  | {
  name: string;
  options: Readonly<Record<string, readonly MessagePart[]>>;
  type: "select";
}
  | {
  type: "pound";
};

---

Node

type Node =
  | ElementNode
  | TextNode;

---

ProblemCodeValue

type ProblemCodeValue = typeof ProblemCode[keyof typeof ProblemCode];

---

Reveal

type Reveal = "nothing" | "score" | "answers";

What a submit returns to the student:

• nothing: just the confirmation (results released later by the host);
• score: score and verdicts;
• answers: score, verdicts and the solution.

---

ScoringRule

type ScoringRule = "all-correct" | "per-slot" | "proportional";

Scoring groups. Every graded component forms one group by default (id = the component's opaque id), or one per part when its definition grades it in parts (ComponentDefinition.groups, a crossword's words), where a slot may sit in several groups.

Rules (n = slots in the group, c = correct slots, P = points):

• all-correct: max P; score P when c = n, else 0. Feedback shows only the group verdict, never which slot is wrong.
• per-slot: max P x n; score P x c.
• proportional: max P; score P x c / n (exact, not rounded).

Selection slots (flags, e.g. options of a multiple-answer choice): an unselected flag gets no verdict, and a group whose flags are all unselected scores 0 with verdict empty.

---

Severity

type Severity = "error" | "warning";

Validation issues. Codes + params, never English sentences: hosts render them with message catalogs (<namespace> of the reporting component, or astl.engine for document-level codes).

---

SlotId

type SlotId = string;

Answers on the wire. Strings only, so any backend in any language can store and grade them.

• A missing key or '' means unanswered.
• Text and number slots: what the student typed.
• Choice slots: the picked value, an opaque option id or a fixed public value (true / false of a statement).
• Flag slots (selection): 'true' when selected.
• Open slots: what the student wrote, kept for a teacher.

---

SlotVerdict

type SlotVerdict = "correct" | "incorrect";

---

Solution

type Solution = Readonly<Record<SlotId, string>>;

Correct answers by slot, shown when the policy reveals them. '' entries are omitted.

---

SourceCompiler

type SourceCompiler = (source, context) => Promise<{
  checker: Checker;
  view: string;
}>;

Turns source HTML (with answers) into a view and a checker for it, for <astl-player> light-DOM sources. Registered by bundles that ship the engine (the HTML-with-answers mode); the player itself never holds answer logic.

• lang: content language of the source (filled from the page when the <astl-doc> has none);
• locale: UI locale of the asking player, for the messages of a failed compile. A failed compile throws; the Error message (plain text, one issue per line) is shown to the author.

Parameters

Parameter	Type
source	string
context	{ lang: string; locale: string; }
context.lang	string
context.locale	string

Returns

Promise<{ checker: Checker; view: string; }>

---

StyleScope

type StyleScope = "document" | "component";

document: the whole exercise (the player's canvas and chrome). component: one element and its subtree.

---

TokenOverrides

type TokenOverrides = Readonly<Record<string, string>>;

Token values by token name without the --astl- prefix, e.g. { accent: '#7a3ff2', 'radius-m': '1rem' }.

---

Translate

type Translate = (key, params?) => string;

Parameters

Parameter	Type
key	string
params?	MessageParams

Returns

string

---

UrlPolicy

type UrlPolicy = (url, context) => boolean;

Decides whether a URL in content may stay: asked with the element's tag and attribute (img and src for a picture in text, a component's tag and its url attribute). Only true keeps it: engines, players and the authoring kit treat a throw or any other answer as no (strictUrlPolicy). Default (isSafeUrl): absolute http:, https: and mailto: URLs.

Parameters

Parameter	Type
url	string
context	{ attribute: string; tag: string; }
context.attribute	string
context.tag	string

Returns

boolean

---

Visibility

type Visibility = "public" | "private" | "derived";

• public: kept in the view as written.
• private: kept only in the answer key / never leaves the server.
• derived: computed by the definition's toView; authors cannot write it.

Variables

BLOCK_TAGS

const BLOCK_TAGS: ReadonlySet<string>;

---

BUILT_IN_PREFIX

const BUILT_IN_PREFIX: "astl-" = 'astl-';

Prefix reserved for built-in Astrolabe elements.

---

CAPTION_TAG

const CAPTION_TAG: "figcaption" = 'figcaption';

---

COMMON_ATTRIBUTES

const COMMON_ATTRIBUTES: readonly AttributeSpec[];

Attributes every component accepts. scoring and points only apply to graded types.

---

CONTENT_ATTRIBUTES

const CONTENT_ATTRIBUTES: ReadonlySet<string>;

Attributes allowed on every content element.

---

DEFAULT_PROFILE

const DEFAULT_PROFILE: NormalisationProfile;

---

DOC_ATTRIBUTES

const DOC_ATTRIBUTES: readonly string[];

Attributes the document and page elements may carry in a view.

---

DOC_TAG

const DOC_TAG: "astl-doc" = 'astl-doc';

---

ELEMENT_TAG_PATTERN

const ELEMENT_TAG_PATTERN: RegExp;

Custom element names that components may use (HTML custom element rules, lowercase ASCII).

---

ENGINE_NAMESPACE

const ENGINE_NAMESPACE: "astl.engine" = 'astl.engine';

i18n namespace of document-level issues reported by the engine.

---

EngineIssue

const EngineIssue: object;

Document-level issue codes. Component codes are listed in each manifest's issues.

Type Declaration

Name	Type	Description
ATTRIBUTE_INVALID	"ATTRIBUTE_INVALID"	-
ATTRIBUTE_REMOVED	"ATTRIBUTE_REMOVED"	-
ATTRIBUTE_REQUIRED	"ATTRIBUTE_REQUIRED"	-
CHILD_COUNT	"CHILD_COUNT"	-
CHILD_OUTSIDE	"CHILD_OUTSIDE"	A child tag of a registered component outside that component (a word to select outside its passage).
CHILD_UNEXPECTED	"CHILD_UNEXPECTED"	-
COMPONENT_NESTED	"COMPONENT_NESTED"	-
DOC_EMPTY	"DOC_EMPTY"	-
DOC_FORMAT_UNSUPPORTED	"DOC_FORMAT_UNSUPPORTED"	-
DOC_LANG_INVALID	"DOC_LANG_INVALID"	-
DOC_LANG_MISSING	"DOC_LANG_MISSING"	-
DOC_MIXED_PAGES	"DOC_MIXED_PAGES"	-
DOC_ROOT_INVALID	"DOC_ROOT_INVALID"	-
ELEMENT_REMOVED	"ELEMENT_REMOVED"	-
ELEMENT_UNKNOWN	"ELEMENT_UNKNOWN"	-
FIGURE_INVALID	"FIGURE_INVALID"	-
ID_DUPLICATE	"ID_DUPLICATE"	-
ID_INVALID	"ID_INVALID"	-
ID_MISSING	"ID_MISSING"	-
IMG_ALT_MISSING	"IMG_ALT_MISSING"	-
NO_COMPONENTS	"NO_COMPONENTS"	-
PAGE_EMPTY	"PAGE_EMPTY"	-
PAGE_NESTED	"PAGE_NESTED"	-
PLACEMENT_INVALID	"PLACEMENT_INVALID"	-
POINTS_INVALID	"POINTS_INVALID"	-
SCORING_MODE_INVALID	"SCORING_MODE_INVALID"	-
SOURCE_TOO_COMPLEX	"SOURCE_TOO_COMPLEX"	-
SOURCE_TOO_DEEP	"SOURCE_TOO_DEEP"	-
SOURCE_TOO_LARGE	"SOURCE_TOO_LARGE"	-
STYLE_TEMPLATE_UNKNOWN	"STYLE_TEMPLATE_UNKNOWN"	-
URL_BLOCKED	"URL_BLOCKED"	-
VERSION_UNSUPPORTED	"VERSION_UNSUPPORTED"	-

---

FIGURE_TAG

const FIGURE_TAG: "figure" = 'figure';

A picture with a caption: a block directly in a page (or the document), holding exactly one img and at most one figcaption (rich inline text), nothing else. A figcaption anywhere else is unwrapped.

---

FLAG_SELECTED

const FLAG_SELECTED: "true" = 'true';

---

FORMAT_VERSION

const FORMAT_VERSION: 1 = 1;

Current content format. Written as format="1" on <astl-doc> in sources and views.

---

icuFormatter

const icuFormatter: MessageFormatter;

The default MessageFormatter. A message with a syntax error renders as its raw text instead of throwing.

---

INLINE_TAGS

const INLINE_TAGS: ReadonlySet<string>;

img is a picture: inline, so it can sit in text, prompts, options and cards.

---

JSON_MEDIA_TYPE

const JSON_MEDIA_TYPE: "application/json" = 'application/json';

---

KEY_FORMAT_VERSION

const KEY_FORMAT_VERSION: 1 = 1;

---

LANGUAGE_TAG_PATTERN

const LANGUAGE_TAG_PATTERN: RegExp;

Loose BCP 47 check: pl, pl-PL, zh-Hant-TW, sr-Latn.

---

MAX_ANSWER_COUNT

const MAX_ANSWER_COUNT: 2000 = 2000;

Most slots one request may carry.

---

MAX_ANSWER_LENGTH

const MAX_ANSWER_LENGTH: 500 = 500;

Longest accepted answer per slot, in Unicode code points, for every slot kind but open. Longer values count as unanswered (engine, servers, protocol 1).

---

MAX_ATTRIBUTES_PER_ELEMENT

const MAX_ATTRIBUTES_PER_ELEMENT: 256 = 256;

Most attributes one element may carry in a source (beyond it: SOURCE_TOO_COMPLEX, checked before parsing).

---

MAX_NESTING_DEPTH

const MAX_NESTING_DEPTH: 100 = 100;

Deepest element nesting a source may have (beyond it: SOURCE_TOO_DEEP).

---

MAX_OPEN_ANSWER_LENGTH

const MAX_OPEN_ANSWER_LENGTH: 2000 = 2000;

Longest open answer, in Unicode code points (so Polish and English letters count one each).

---

MAX_REQUEST_BYTES

const MAX_REQUEST_BYTES: number;

Largest request body servers should accept, in bytes.

---

MAX_SOURCE_LENGTH

const MAX_SOURCE_LENGTH: 1000000 = 1_000_000;

Largest accepted source, in UTF-16 code units.

---

OPAQUE_ID_PATTERN

const OPAQUE_ID_PATTERN: RegExp;

Opaque ids in views: k + 16 lowercase base32 characters (80 bits of an HMAC-SHA-256).

---

OPEN_SLOT_KIND

const OPEN_SLOT_KIND: "open" = 'open';

The built-in slot kind of open answers: stored with the attempt for a teacher, never graded.

---

PAGE_ATTRIBUTES

const PAGE_ATTRIBUTES: readonly string[];

---

PAGE_TAG

const PAGE_TAG: "astl-page" = 'astl-page';

---

PlayerEvent

const PlayerEvent: object;

DOM events. All bubble and are composed (they cross shadow roots).

Type Declaration

Name	Type	Description
change	"astl-change"	From an element when the student changes an answer. Detail: ChangeDetail.
error	"astl-error"	Loading or grading failed. Detail: ErrorDetail.
page	"astl-page"	Page changed. Detail: PageDetail.
ready	"astl-ready"	From <astl-player> when the view is mounted and elements are attached. Detail: ReadyDetail.
result	"astl-result"	A check or submit finished. Detail: the CheckResponse or SubmitResponse.
snapshot	"astl-snapshot"	Snapshot to persist (debounced). Detail: Snapshot.
state	"astl-state"	Attempt state changed. Detail: StateDetail.

---

PRACTICE_POLICY

const PRACTICE_POLICY: AttemptPolicy;

---

PROBLEM_MEDIA_TYPE

const PROBLEM_MEDIA_TYPE: "application/problem+json" = 'application/problem+json';

---

ProblemCode

const ProblemCode: object;

Type Declaration

Name	Type	Description
attemptClosed	"attempt_closed"	409: the attempt is already submitted.
checkNotAllowed	"check_not_allowed"	403: checking is not allowed under this policy (tests).
checksExhausted	"checks_exhausted"	403: the practice policy's maxChecks is used up.
internal	"internal_error"	500: unexpected server error.
invalidRequest	"invalid_request"	400: body is not valid JSON or does not match the request schema.
methodNotAllowed	"method_not_allowed"	405: wrong method.
notFound	"not_found"	404: unknown attempt or page.
payloadTooLarge	"payload_too_large"	413: body too large.
unauthorized	"unauthorized"	401: the host could not identify the attempt.

---

PROTOCOL_VERSION

const PROTOCOL_VERSION: 1 = 1;

Grading protocol over HTTP. Any backend in any language can implement it:

POST {endpoint}/check body CheckRequest -> 200 CheckResponse POST {endpoint}/submit body SubmitRequest -> 200 SubmitResponse

{endpoint} identifies one attempt (e.g. /api/attempts/123); how it is authorised is up to the host (cookie, bearer token). Errors are application/problem+json (RFC 9457) with a code from ProblemCode.

---

ProtocolPath

const ProtocolPath: object;

Type Declaration

Name	Type
check	"check"
submit	"submit"

---

REMOVED_WITH_CONTENT

const REMOVED_WITH_CONTENT: ReadonlySet<string>;

Dropped together with their content: active content, embeds, media and form controls.

---

SCORING_ATTRIBUTES

const SCORING_ATTRIBUTES: readonly AttributeSpec[];

---

SCORING_RULES

const SCORING_RULES: readonly ScoringRule[];

---

SNAPSHOT_FORMAT

const SNAPSHOT_FORMAT: 1 = 1;

---

SOURCE_ID_PATTERN

const SOURCE_ID_PATTERN: RegExp;

Author ids: a letter, then letters, digits, _ or -; at most 64 characters. Unique within one document.

---

STYLE_TEMPLATE_ATTRIBUTE

const STYLE_TEMPLATE_ATTRIBUTE: "style-template" = 'style-template';

The attribute that picks a template, on <astl-doc> and on every component.

---

STYLE_TEMPLATE_NAME

const STYLE_TEMPLATE_NAME: RegExp;

Template names: lowercase kebab-case, 1 to 40 characters, starting with a letter.

---

SUPPORTED_FORMATS

const SUPPORTED_FORMATS: readonly number[];

---

TAG_ATTRIBUTES

const TAG_ATTRIBUTES: Readonly<Record<string, readonly string[]>>;

Extra attributes allowed on specific rich-text elements. A picture: src and alt (required; alt="" marks decoration), width and height (positive integers, so the layout does not jump while it loads).

---

TEST_POLICY

const TEST_POLICY: AttemptPolicy;

---

URL_ATTRIBUTES

const URL_ATTRIBUTES: Readonly<Record<string, string>>;

The attribute of a rich-text element that holds a URL, checked by the URL policy.

Functions

allAttributes()

function allAttributes(manifest): readonly AttributeSpec[];

Every attribute an element of this type may carry, common ones first.

Parameters

Parameter	Type
manifest	ComponentManifest

Returns

readonly AttributeSpec[]

---

checkCatalog()

function checkCatalog(catalog): CatalogProblem[];

Problems of catalog alone (syntax and plural coverage).

Parameters

Parameter	Type
catalog	MessageCatalog

Returns

CatalogProblem[]

---

childElements()

function childElements(node, tag?): ElementNode[];

Element children with the given tag, in order.

Parameters

Parameter	Type
node	ElementNode
tag?	string

Returns

ElementNode[]

---

childTagConflict()

function childTagConflict(manifests):
  | {
  components: readonly [string, string];
  tag: string;
}
  | null;

A child tag two of the manifests declare with specs that differ (see sameChildSpec), or null when none does.

Parameters

Parameter	Type
manifests	readonly ComponentManifest[]

Returns

| { components: readonly [string, string]; tag: string; } | null

---

compareCatalogs()

function compareCatalogs(source, translation): CatalogProblem[];

Problems of a translation compared with its source catalog (same namespace).

Parameters

Parameter	Type
source	MessageCatalog
translation	MessageCatalog

Returns

CatalogProblem[]

---

createI18n()

function createI18n(options): I18n;

Parameters

Parameter	Type
options	CreateI18nOptions

Returns

I18n

---

directionOf()

function directionOf(lang): Direction;

Writing direction for a BCP 47 tag, e.g. he -> rtl, pl-PL -> ltr. Script subtags win (az-Arab).

Parameters

Parameter	Type
lang	string

Returns

Direction

---

element()

function element(
   tag,
   attrs?,
   children?
): ElementNode;

Parameters

Parameter	Type	Default value
tag	string	undefined
attrs?	Readonly<Record<string, string>>	{}
children?	readonly Node[]	[]

Returns

ElementNode

---

fitsAnswer()

function fitsAnswer(value, kind?): boolean;

Whether value is within the length limit of a slot of kind, counted in Unicode code points.

Parameters

Parameter	Type
value	string
kind?	string

Returns

boolean

---

groupMax()

function groupMax(
   rule,
   points,
   slotCount
): number;

Group maximum for a rule.

Parameters

Parameter	Type
rule	ScoringRule
points	number
slotCount	number

Returns

number

---

hasErrors()

function hasErrors(issues): boolean;

Parameters

Parameter	Type
issues	readonly Issue[]

Returns

boolean

---

isAnswerKey()

function isAnswerKey(value): value is AnswerKey;

Narrow check for keys loaded from storage. Full validation happens in the engine.

Parameters

Parameter	Type
value	unknown

Returns

value is AnswerKey

---

isAnswers()

function isAnswers(value): value is Readonly<Record<string, string>>;

Type guard for untrusted input (request bodies, storage).

Parameters

Parameter	Type
value	unknown

Returns

value is Readonly<Record<string, string>>

---

isAttemptPolicy()

function isAttemptPolicy(value): value is AttemptPolicy;

Parameters

Parameter	Type
value	unknown

Returns

value is AttemptPolicy

---

isElement()

function isElement(node, tag?): node is ElementNode;

Parameters

Parameter	Type
node	Node | undefined
tag?	string

Returns

node is ElementNode

---

isOpaqueId()

function isOpaqueId(value): boolean;

Parameters

Parameter	Type
value	string

Returns

boolean

---

isProblemDetails()

function isProblemDetails(value): value is ProblemDetails;

Parameters

Parameter	Type
value	unknown

Returns

value is ProblemDetails

---

isSafeUrl()

function isSafeUrl(url): boolean;

The default URL policy: absolute http:, https: and mailto: URLs (tabs and newlines ignored, as browsers do).

Parameters

Parameter	Type
url	string

Returns

boolean

---

isSnapshot()

function isSnapshot(value): value is Snapshot;

Parameters

Parameter	Type
value	unknown

Returns

value is Snapshot

---

isSourceId()

function isSourceId(value): boolean;

Parameters

Parameter	Type
value	string

Returns

boolean

---

isStyleTemplate()

function isStyleTemplate(value): value is StyleTemplate;

Whether value has the shape of a StyleTemplate: a valid name, a positive version, one or both scopes, string tags, a namespace, and records of strings for tokens and parts. Registries use it for hosts without type checking.

Parameters

Parameter	Type
value	unknown

Returns

value is StyleTemplate

---

maxAnswerLength()

function maxAnswerLength(kind): number;

The longest answer a slot of kind accepts, in code points: 2000 for open slots, 500 for the others.

Parameters

Parameter	Type
kind	string | undefined

Returns

number

---

messageParams()

function messageParams(parts): Set<string>;

Names of all arguments a message uses, including plural and select selectors.

Parameters

Parameter	Type
parts	readonly MessagePart[]

Returns

Set<string>

---

negotiateLocale()

function negotiateLocale(
   requested,
   available,
   fallback
): string;

BCP 47 lookup (RFC 4647 section 3.4, extended): for each requested tag try the tag, then shorter prefixes (pl-PL -> pl), then any available tag with the same language (pt -> pt-BR). Case-insensitive.

Parameters

Parameter	Type
requested	readonly string[]
available	readonly string[]
fallback	string

Returns

string

---

parseMessage()

function parseMessage(message): MessagePart[];

Parameters

Parameter	Type
message	string

Returns

MessagePart[]

---

pluralCategories()

function pluralCategories(locale, ordinal?): readonly string[];

Plural categories a locale needs, e.g. pl -> one, few, many, other.

Parameters

Parameter	Type	Default value
locale	string	undefined
ordinal?	boolean	false

Returns

readonly string[]

---

roundScore()

function roundScore(value): number;

Rounds a score for display: at most 2 decimals, no trailing zeros.

Parameters

Parameter	Type
value	number

Returns

number

---

sameChildSpec()

function sameChildSpec(a, b): boolean;

Whether two child specs may share a tag: the same visibility and attributes (in any order), so the tag carries the same data and keeps the same things private in every type that declares it (astl-prompt, astl-option). Content and counts are each type's own: a select's options are plain text, a choice's options rich.

Parameters

Parameter	Type
a	ChildSpec
b	ChildSpec

Returns

boolean

---

strictUrlPolicy()

function strictUrlPolicy(policy): UrlPolicy;

A host's URL policy as engines, players and the authoring kit use it: a URL passes only when the policy returns true. A policy that throws, or returns anything else (the Promise of an async function, say), blocks the URL.

Parameters

Parameter	Type
policy	UrlPolicy

Returns

UrlPolicy

---

text()

function text(value): TextNode;

Parameters

Parameter	Type
value	string

Returns

TextNode

---

textContent()

function textContent(node): string;

Concatenated text of a subtree, like DOM textContent.

Parameters

Parameter	Type
node	Node

Returns

string

---

variantAttribute()

function variantAttribute(variants): AttributeSpec;

The variant attribute of a type with variants: an enum of the manifest's variant names.

Parameters

Parameter	Type
variants	VariantSpec

Returns

AttributeSpec