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 Mika’s descriptor with `mikaPlugin({ entrypoint })`.
`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, { api })`, reads sellables, and renders copied purchase components.
`src/components/ProductPurchase.astro` and form components	Copied template owned by host after copy	Render HTML forms whose `action` values use `actions.mika.*.queryString`; 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, { api })` 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() carries descriptor-safe options only. Use entrypoint, maintenance, and assertWired there; keep live API functions in a native entrypoint:

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

The entrypoint module exports createPlugin() and calls createMikaPlugin({ api }) from @bnomei/emdash-mika/server 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, { api }), 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, { api })`	Receives the host API explicitly from the request-bound page or endpoint.	Server-only Astro page or endpoint helper.
`createMikaActions({ api })`	Receives the host API explicitly from `src/actions/index.ts`.	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 fixture pages so tests can force local fixture behavior. Production pages should import the same host API used by the entrypoint and actions registry, then pass it explicitly.

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, { api }) from @bnomei/emdash-mika/astro.
Mika resolves sellables through the same host API passed to the native plugin entrypoint and Actions registry.
Copied components render visible purchase controls and forms whose action values use actions.mika.*.queryString.

Form mutation flow:

A copied form posts to an Astro Action URL such as actions.mika.cart.add.queryString.
Astro dispatches the action registered in src/actions/index.ts.
createMikaActions({ api }) 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/server.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