Post-identity-transform hook for rune packages

Options Considered

1. Keep ad-hoc function composition (status quo)

Each post-processor exports a standalone tree transform function. Users manually compose them in their page load function:

const renderable = math(hl(transform(serialized)));

Pros:

• No framework changes needed
• Explicit composition — easy to understand call order

Cons:

• Does not scale: each new post-processor adds manual wiring
• Community packages cannot participate without user intervention
• No standard way to aggregate contributed CSS
• Every SvelteKit adapter, Astro adapter, etc. must independently wire the same composition

2. Post-identity-transform hook on RunePackage

Add a new hook type to RunePackage that declares tree transforms to run after the identity transform:

interface RunePackage {
  // ... existing fields ...
  postIdentityTransform?: PostIdentityTransformHook[];
}

interface PostIdentityTransformHook {
  /** Human-readable name for debugging/logging */
  name: string;
  /** Factory that returns the tree transform (may be async for lazy loading) */
  init: () => Promise<TreeTransformFn> | TreeTransformFn;
  /** Optional CSS contributed by this transform */
  css?: string | (() => string | Promise<string>);
}

type TreeTransformFn = (tree: RendererNode) => RendererNode;

The createTransform() factory (or a new orchestrator) collects all hooks from loaded packages and chains them after the identity transform, in package order (core first, then community in config order).

Pros:

• Packages are self-contained: schema + config + post-transform hook ship together
• Automatically composed — no manual wiring in page load functions
• CSS aggregation is built in
• Framework adapters (SvelteKit, Astro) get post-processing for free
• init() factory supports lazy initialization (Shiki's async highlighter creation)
• Scales to any number of community packages

Cons:

• New concept to learn for package authors
• Ordering between community package hooks may matter in edge cases
• Slightly more indirection than explicit function composition

3. Post-identity-transform hook on ThemeConfig

Same as Option 2, but place the hook on ThemeConfig instead of RunePackage.

Pros:

• Theme controls all presentation, including post-processing

Cons:

• Conflates presentation config (declarative) with programmatic transforms
• A math package is not a "theme" — it's a rune package that happens to need post-processing
• Breaks the principle that RunePackage is the unit of distribution

4. Generic plugin system with lifecycle hooks

Introduce a full plugin architecture with named lifecycle phases:

interface RefraktPlugin {
  name: string;
  hooks: {
    beforeTransform?: (tree) => tree;
    afterTransform?: (tree) => tree;
    beforeRender?: (tree) => tree;
    // ... etc
  };
}

Pros:

• Maximum flexibility for future extension points

Cons:

• Over-engineered for the current need (only one hook point is missing)
• Introduces a parallel extension mechanism alongside RunePackage
• More API surface to maintain and document