![\"Amiriel](\"https://amiriel.com/logo/amiriel_256x256.webp\"){kind=logo}
\n\n \n
\n Framework-agnostic TypeScript core for Amiriel letter documents.\n
\n\n`@amiriel/core` is the shared model and rules layer used by framework packages such as\n[`@amiriel/vue`](https://github.com/Amirieljs/Amiriel-Vue) for Vue and\n[`@amiriel/react`](https://github.com/Amirieljs/Amiriel-React) for React. It\ncontains no UI framework, DOM, storage, authentication, routing, or database\ncode.\n\n[](https://www.npmjs.com/package/@amiriel/core)\n[](https://www.npmjs.com/package/@amiriel/core)\n[]()\n\nPrefer the short package name? Install [`amiriel`](https://www.npmjs.com/package/amiriel) instead — it re-exports everything from this package.\n\n## Features\n\n- Shared Amiriel document types\n- Document normalization helpers\n- Paper size constraints and media placement math\n- Built-in themes and CSS variable generation\n- English and Chinese UI label helpers\n- Font, text color, and video duration utilities\n- Framework-agnostic ESM package with TypeScript declarations\n\n## Install\n\n```bash\nnpm install @amiriel/core@beta\npnpm add @amiriel/core@beta\nyarn add @amiriel/core@beta\nbun add @amiriel/core@beta\n```\n\nOr use the meta package:\n\n```bash\nnpm install amiriel@beta\n```\n\n## Usage\n\n```ts\nimport {\n normalizeDocument,\n type AmirielDocument,\n} from \"@amiriel/core\";\n\nconst document: AmirielDocument = normalizeDocument({\n theme: \"midnight\",\n media: [],\n pages: [],\n});\n```\n\n### Custom id generation\n\n`normalizeDocument` may assign page or placement ids when input omits them.\nIn modern Node.js and browsers it uses `crypto.randomUUID()` when available.\nYou can also pass your own id factory:\n\n```ts\nimport { normalizeDocument } from \"@amiriel/core\";\n\nconst document = normalizeDocument(input, {\n createId: () => `doc-${Date.now()}`,\n});\n```\n\n### Themes\n\nBuilt-in themes: `midnight`, `paper`, `memorial`.\n\n```ts\nimport {\n amirielThemeCssVars,\n findAmirielThemeDefinition,\n} from \"@amiriel/core\";\n\nconst theme = findAmirielThemeDefinition(\"paper\");\nconst cssVars = amirielThemeCssVars(theme);\n```\n\n### Labels\n\n```ts\nimport { resolveAmirielLabels } from \"@amiriel/core\";\n\nconst labels = resolveAmirielLabels(\"zh\", {\n uploadMedia: \"选择照片或视频\",\n});\n```\n\n## Main Exports\n\n| Export | Description |\n| --- | --- |\n| Document types | `AmirielDocument`, `AmirielPage`, `AmirielMedia`, and related shapes |\n| `normalizeDocument` | Normalize document input into the shared Amiriel shape |\n| Theme helpers | Built-in theme definitions, CSS variable generation, and merge utilities |\n| Label helpers | Built-in English and Chinese UI labels with partial overrides |\n| Placement math | Paper sizing, media placement, and text block normalization utilities |\n\n## Package Architecture\n\n| npm package | Repository | Role |\n| --- | --- | --- |\n| `@amiriel/core` | [Amirieljs/Amiriel-Core](https://github.com/Amirieljs/Amiriel-Core) | Framework-agnostic core (this repo) |\n| `amiriel` | [Amirieljs/Amiriel](https://github.com/Amirieljs/Amiriel) | Meta package re-exporting `@amiriel/core` |\n| `@amiriel/vue` | [Amirieljs/Amiriel-Vue](https://github.com/Amirieljs/Amiriel-Vue) | Vue 3 implementation |\n| `@amiriel/react` | [Amirieljs/Amiriel-React](https://github.com/Amirieljs/Amiriel-React) | React implementation |\n| `@amiriel/vanilla` | [Amirieljs/Amiriel-Vanilla](https://github.com/Amirieljs/Amiriel-Vanilla) | Vanilla JS implementation |\n\nFramework packages depend on `@amiriel/core` for document normalization, theme\ndefinitions, labels, and placement math.\n\nThe full hosted product lives at [amiriel.com](https://amiriel.com).\n\n## License\n\nMIT. The core package is open source and can be used commercially. The official\nhosted Amiriel product at [amiriel.com](https://amiriel.com) may still provide\npaid services around storage, accounts, delivery, hosting, collaboration, or\nother product workflows.\n","readmeFilename":"README.md"}