@openawb/experience

Framework-agnostic runtime for executing exported AWB experiences (.awb.zip or unpacked directories).

AWB is the authoring tool. This package is the execution layer. Host apps (Next.js, React, Vue, Astro, or vanilla JS) mount an experience into a DOM container without shipping the editor.

Install

pnpm add @openawb/experience @openawb/types
# optional peer for bundling published motion runtimes:
pnpm add -D esbuild

Import rules

// Runtime
import { createExperience, prepareMountMarkup } from "@openawb/experience";
// or
import { createExperience } from "@openawb/experience/createExperience";

// Contracts
import type { AwbExperienceManifest, AssetResolver } from "@openawb/types";
import { parseAwbExperienceManifest } from "@openawb/types";

Manifest / asset types are not re-exported from this package root — import them from @openawb/types.

Quick start

import { createExperience } from "@openawb/experience";

const experience = await createExperience({
  source: { type: "url", url: "https://cdn.example.com/site.awb.zip" },
});

await experience.mount(document.getElementById("experience")!);

// later
experience.destroy();

Sources

| Source | Description | | --- | --- | | { type: "url", url } | Fetch a .awb.zip | | { type: "arrayBuffer" \| "uint8Array", data } | In-memory zip bytes | | { type: "directory", baseUrl } | Unpacked package (manifest.json at the root) |

Manifest

Every package includes manifest.json (format: "awb-experience"). See @openawb/types for the schema and parseAwbExperienceManifest.

Host integration tips

1. Mount into a slot that does not use overflow: hidden if the experience uses position: sticky.
2. Let the experience root grow (min-height) — do not clip long pages to a fixed 100% height.
3. SEO belongs to the host (CMS / Next metadata), not the experience package.
4. Pass an AssetResolver when packages still reference asset: ids:

import type { AssetResolver } from "@openawb/types";

const assetResolver: AssetResolver = {
  resolve(assetId) {
    return { id: assetId, url: `https://cdn.example.com/${assetId}` };
  },
};

Subpath exports

| Path | Use | | --- | --- | | @openawb/experience | Host mount API + published helpers | | @openawb/experience/createExperience | Mount/load only | | @openawb/experience/published | GSAP / motion runtimes shared with the builder preview | | @openawb/experience/action | Node action execution helpers | | @openawb/experience/event | Interaction runtime |

Preview parity

The AWB builder preview consumes the same motion and interaction runtimes (GsapMotionRuntime, bindInteractionRuntime, …) so canvas preview stays aligned with production execution.

Development

pnpm --filter @openawb/experience test
pnpm --filter @openawb/experience typecheck
pnpm --filter @openawb/experience build

See Publishing.