@williamcachamwri/markui-core

Framework-neutral contracts used by every MarkUI package: the versioned UI AST, safe expressions, component schemas, diagnostics and immutable state-path helpers.

Install

npm install @williamcachamwri/markui-core

Versioned documents

import {
  MARKUI_DOCUMENT_VERSION,
  assertMarkUIDocumentVersion,
  type MarkUIDocument,
} from '@williamcachamwri/markui-core'

const document: MarkUIDocument = {
  type: 'document',
  version: MARKUI_DOCUMENT_VERSION,
  frontmatter: {},
  children: [],
}

assertMarkUIDocumentVersion(document)

A runtime must reject unsupported document versions instead of trying to render an incompatible AST.

Safe expressions

import { evaluateExpression } from '@williamcachamwri/markui-core'

const value = evaluateExpression('price * quantity', {
  price: 12,
  quantity: 3,
  helpers: {},
})

Expressions are parsed without eval or new Function. They can read values, use supported operators and call helpers supplied through context.helpers. Constructor/prototype access and arbitrary method calls are blocked. Parsed expressions use a bounded LRU cache.

Immutable state paths

import { getPath, setPathImmutable } from '@williamcachamwri/markui-core'

const current = { user: { profile: { name: 'Ada' } } }
const next = setPathImmutable(current, 'user.profile.name', 'Grace')

getPath(next, 'user.profile.name') // "Grace"
current.user.profile.name // "Ada"

setPathImmutable preserves the previous value and clones only the changed path.

Component registry

import { ComponentRegistry } from '@williamcachamwri/markui-core'

const registry = new ComponentRegistry([
  {
    name: 'badge',
    allowChildren: true,
    props: {
      tone: { type: 'string', enum: ['neutral', 'success', 'danger'] },
    },
  },
])

The compiler uses registry definitions to report unknown components, invalid props, missing required props and invalid child usage with source positions.

Main exports

• AST and value types such as MarkUIDocument, UINode and MarkUIValue.
• MARKUI_DOCUMENT_VERSION and assertMarkUIDocumentVersion.
• compileTemplate, evaluateExpression and resolveValue.
• ComponentRegistry and createDefaultRegistry.
• getPath, setPathImmutable and diagnostics utilities.

Security boundary

Expression helpers are trusted application code. Do not expose helpers that execute arbitrary source, access secrets without authorization or bypass application validation. Raw HTML is not handled by this package; sanitization remains the renderer's responsibility.