Integration File Map

Use this page when a code sample says “copy this”, “import this”, or “register this” and you need to know which runtime owns the file.

Mika is not a hidden storefront runtime. An Astro + EmDash host wires the package through ordinary Astro and EmDash files:

File or surface	Owner	What happens there
`astro.config.mjs`	Host app	Registers EmDash as an Astro integration, configures EmDash database/storage, and installs `mikaPlugin({ api })`.
`src/lib/mika-api.ts`	Host app	Builds or exports the host-owned `MikaApi` implementation used by plugin routes, Astro Actions, and request-bound page helpers.
`src/actions/index.ts`	Host app	Exports Astro’s `server` action tree and applies host action policy such as rate limits or account checks.
`src/actions/mika.ts`	Copied template owned by host after copy	Re-exports `createMikaActions` from `@bnomei/emdash-mika/astro-actions` so copied forms stay aligned with the package version.
`src/pages/products/[slug].astro` or equivalent	Host app	Loads the host product entry, calls `createMika(Astro)`, reads sellables, and renders copied purchase components.
`src/components/ProductPurchase.astro` and form components	Copied template owned by host after copy	Render HTML forms that post to `actions.mika.*`; they are not package-owned runtime routes.
`src/pages/cart.astro`, `src/pages/account.astro`, checkout pages, download endpoint, webhook endpoint	Copied template owned by host after copy	Request-bound pages/endpoints that call `createMika(Astro)` and usually export `prerender = false`.
`/_emdash/api/plugins/mika/<route>`	EmDash plugin route table from Mika	JSON plugin routes registered by `mikaPlugin`; public reads are limited to catalog sellables and stock availability.
`/_emdash/admin`	EmDash	Admin UI. Mika can contribute admin action manifests and runner-backed operations, but the admin app is EmDash-owned.
`src/pages/llms.txt.ts` and `.well-known/mika-agent.json.ts`	Copied template owned by host after copy	Public metadata that describes capabilities and boundaries; it does not grant tool access.

Descriptor Options Versus Native Entrypoints

mikaPlugin({ api }) is the short form when the API/options can travel through EmDash’s descriptor path in your setup.

When the API is function-heavy, or when it needs to merge runtime-only imports, use a native entrypoint instead:

const mikaTemplatePlugin = mikaPlugin({ entrypoint: "#mika-template-plugin" });

The entrypoint module exports createPlugin() and calls Mika’s runtime createPlugin({ api }) with local function overrides. The seeded template uses this pattern in src/plugins/mika-template-plugin.ts so fixture API functions are imported at runtime instead of serialized through descriptor options.

Import Versus Copy

Import package subpaths when you need contracts or factories:

@bnomei/emdash-mika for mikaPlugin;
@bnomei/emdash-mika/astro for createMika(Astro), money formatting, redirect helpers, and hidden-input helpers;
@bnomei/emdash-mika/astro-actions from src/actions/mika.ts;
@bnomei/emdash-mika/server, /provider, /stripe, /admin, /agent, /acp, /email, and /types for their scoped server, provider, admin, metadata, and type contracts.

Copy template files when you want host-owned pages and components:

source package path: ../emdash-mika/src/templates/astro/**;
npm export path: @bnomei/emdash-mika/templates/astro/*;
destination in a host Astro app: usually src/actions/, src/components/, src/lib/, src/pages/, and src/styles/.

After copy, those files are yours. Change layout, routes, copy, auth checks, localization, and provider policy in the host app.

Which API Object Is Used

Mika has three common API resolution paths:

Call site	How it finds the API	Boundary
`createMika(Astro)`	Uses the default API registered by the active Mika plugin, unless the page passes `createMika(Astro, { api })`.	Server-only Astro page or endpoint helper.
`createMikaActions()`	Uses the default API registered by the active Mika plugin, unless `createMikaActions({ api })` is passed.	Astro Actions for HTML forms and typed action clients.
`createMikaClient()`	Calls public plugin JSON reads with `fetch`.	Browser-safe catalog and stock reads only.

The seeded template passes createMika(Astro, { api: mikaApiOverrides }) on some fixture pages so tests can force local fixture behavior. Production pages normally rely on the plugin-registered API unless they have a clear reason to override it.

Request Flow

Product page flow:

Astro routes the request to a host page such as src/pages/products/[slug].astro.
The page loads the host product entry from EmDash, content collections, or another content source.
The page calls createMika(Astro) from @bnomei/emdash-mika/astro.
Mika resolves sellables through the same host API registered with mikaPlugin({ api }).
Copied components render visible purchase controls and forms that post to actions.mika.*.

Form mutation flow:

A copied form posts to an Astro Action such as actions.mika.cart.add.
Astro dispatches the action registered in src/actions/index.ts.
createMikaActions() validates the form input and builds a request context from the Astro action context.
The operation runs through the host-owned MikaApi.
The page reads the result with Astro.getActionResult(...) and renders feedback or redirects to the checkout provider.

Plugin route flow:

EmDash serves Mika plugin routes under /_emdash/api/plugins/mika/.
Mika’s operation descriptors map route keys to paths, methods, schemas, public visibility, and agent metadata.
Only catalog/sellables and sellables/availability are public reads.
Mutation, account, checkout, webhook, admin, and agent-tool operations need host policy, trusted callers, or copied host endpoints.

External References

Astro Actions define type-safe backend functions in src/actions/index.ts and can be called from HTML form actions.
Astro on-demand rendering explains adapters, output: "server", and per-route export const prerender = false.
EmDash getting started shows the standard Astro project shape with astro.config.mjs, database, and storage configuration.
EmDash plugin guide describes the descriptor/runtime plugin model Mika registers into.

Astro Storefront follows the copied Actions and UI path.
Backend And Provider follows the host API and provider path.
Plugin Routes lists exact plugin route keys and public route rules.

Source Anchors

ⓟ ../emdash-mika/package.json
ⓟ ../emdash-mika/src/plugin.ts
ⓟ ../emdash-mika/src/api/routes.ts
ⓟ ../emdash-mika/src/api/operations.ts
ⓟ ../emdash-mika/src/api/runtime-api.ts
ⓟ ../emdash-mika/src/api/client.ts
ⓟ ../emdash-mika/src/astro.ts
ⓟ ../emdash-mika/src/astro-actions.ts
ⓐ ../emdash-mika/src/templates/astro/README.md
ⓐ ../emdash-mika/src/templates/astro/actions/index.ts
ⓐ ../emdash-mika/src/templates/astro/actions/mika.ts
ⓣ ../emdash-mika-template/astro.config.mjs
ⓣ ../emdash-mika-template/src/lib/mika-api.ts
ⓣ ../emdash-mika-template/src/plugins/mika-template-plugin.ts