@endora-commerce/mod-invoices 0.0.0-stage → 0.100.0

package/dist/ports/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The port interfaces `invoices` publishes whose signature carries a MikroORM
+ * `EntityManager`, and **nothing that exists at runtime** (feature 080, T048;
+ * D-169, D-171).
+ *
+ * `tsc` compiles this file to `export {};`. That is the property D-171 makes
+ * the boundary decision on — *a subpath is contract surface iff the module it
+ * resolves to exports no runtime binding* — and it is why this declaration has
+ * its own file rather than sitting on top of a service module, which exports
+ * the class beside it. A consumer naming that file names the owner's
+ * implementation, whatever `import type` erases; a consumer naming this one
+ * names a declaration and can name nothing else.
+ *
+ * **This is not yet a supported specifier and the ledger still counts it.**
+ * `invoices` is not a workspace package, so there is no `exports` map for this
+ * to be a subpath of, and `check:module-boundary` reads `orders`' relative
+ * import exactly as it read the entity import it replaces — D-171 says so in as
+ * many words: `resolveModulePackage` returns `null` for any specifier starting
+ * with `.`, so an unconverted reach has no subpath for the exemption to apply
+ * to, and reaching the exempt state takes three separable edits (package the
+ * owner, publish the interface, rewrite the specifier). This file is the second
+ * of those three, taken early because it is the one that does not need the
+ * module to move.
+ *
+ * The rest of this module's surface is in `@endora-commerce/contracts` and
+ * belongs there — `InvoiceReadPort`, `InvoicePdfPort`, `CorrectiveInvoicePort`
+ * are contract DTOs end to end. This one qualifies for `./ports` on D-171's own
+ * test — *"does this signature stop the interface living in
+ * `packages/contracts`"* — and the answer is its `EntityManager` parameter,
+ * which that package may not name because `admin` and `storefront` both compile
+ * it (FR-034).
+ *
+ * No entity class leaves by this door, type-only included (D-168).
+ */
+import type { EntityManager } from '@mikro-orm/postgresql';
+/**
+ * What {@link InvoicePlacementApplyPort.createProformaForOrder} answers — a
+ * published record and never the managed entity (D-77's first narrowing).
+ * `orders` reads nothing off it today; it is returned so that the caller can
+ * tell "opened" from "the owner is absent and opened nothing", which is a state
+ * this seam really has.
+ */
+export interface ProformaInvoiceOpened {
+    readonly id: string;
+    readonly orderId: string;
+    readonly number: string;
+}
+/**
+ * Container name: `invoicePlacementApplyPort`. Owner: `invoices`.
+ *
+ * The proforma document order placement opens, written on the **caller's**
+ * `EntityManager` (D-169). `orders` is the one consumer, and it makes one call.
+ *
+ * **The seam is not a defect in the design, it *is* the design.**
+ * `invoices_order_fk` (`invoices.order_id` -> `orders.id`, `on delete restrict`,
+ * `db/migrations/20260425T050720_core_commerce_init.ts`) means the row cannot
+ * exist before its order does, and the order does not commit until placement
+ * returns — so a port that opened its own transaction could not satisfy a
+ * foreign key against a row it cannot see. A foreign key needs the **table**
+ * and never the class (D-169), so that constraint stands while this module
+ * publishes no entity class by name.
+ *
+ * **The read half is not here.** The customer download and the admin bulk print
+ * go through `InvoiceReadPort` / `InvoicePdfPort` in
+ * `@endora-commerce/contracts`, and a read handed an `EntityManager` would be a
+ * write seam re-opened to serve a read (D-169).
+ *
+ * **Owner off:** this module is switchable (`invoices.enabled`), and `orders`
+ * declares the edge `degrades-without` rather than binding it — an acknowledged
+ * edge would keep the bind and make that control unusable, because `orders` is
+ * non-deactivatable. So placement asks `effectiveState.isPresent('invoices')`
+ * and, when the answer is no, opens no proforma and changes nothing else about
+ * the order. That is what the setting's own description promises an operator —
+ * *"switches invoice issuance … on or off"* — and it is what the platform did
+ * **not** do before T048: the row was written straight into this module's table
+ * while the operator had switched it off, which is the shape issue #188 names.
+ */
+export interface InvoicePlacementApplyPort {
+    /**
+     * Open the proforma an order is placed with.
+     *
+     * `em` is **required** (D-169). Its one caller is `placeOrder`, which always
+     * passes the `EntityManager` its own transaction runs on; an optional
+     * parameter is what lets the same method double as a standalone transaction,
+     * and that is a lie about a seam a foreign key holds together.
+     */
+    createProformaForOrder(em: EntityManager, input: {
+        orderId: string;
+        currency: string;
+        total: string;
+    }): Promise<ProformaInvoiceOpened>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/ports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;;;OAOG;IACH,sBAAsB,CACpB,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAC1D,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACnC"}

package/dist/ports/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/ports/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":""}

package/docs/invoices.md

@@ -0,0 +1,113 @@
+---
+title: invoices
+description: PDF invoice / proforma generation + asset linkage
+---
+
+# `invoices`
+
+Generates proforma and final invoice PDFs, registers them under the
+`assets` module, and links them from the originating Order.
+
+## Public surface
+
+Admin list is gated by `orders:read`.
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/orders/:id/invoice` | customer | Download invoice PDF (404 `INVOICE_NOT_READY` until status='ready'; binary Content-Type once ready). Admin uses the same endpoint via the storefront origin to re-download. |
+| `GET /api/v1/admin/invoices` | admin | List all invoices with `filter[status]` / `filter[orderId]`; default limit 50, capped at 200 |
+
+## Generation flow
+
+`invoice-service.ts#generate()` runs after `order.confirmed`: pulls the
+Order + items + buyer Address snapshot, renders a PDF via a small,
+dependency-light renderer, persists the bytes through the `assets` module,
+and writes the asset id back onto the Order. Failures emit
+`invoice.generation_failed.v1` for an admin retry queue.
+
+## Entities
+
+`Invoice` (number, issued/dated timestamps, asset reference,
+`type ∈ {proforma, final}`).
+
+## Numbering
+
+Two facts about an invoice number pull in opposite directions, and both are
+deliberate:
+
+- the **sequence** is drawn per `(sales channel, kind, year)`, gap-free, under a
+  row lock — `invoice_number_counters`;
+- the **number** is unique across the whole platform — `invoices_number_unique`.
+
+What turns the first into the second is a pattern, held in a Setting per
+document kind and scopable per sales channel:
+
+| Kind | Setting | Default |
+| --- | --- | --- |
+| VAT invoice | `invoices.numbering.invoice.pattern` | `FV {seq}/{channel}/{YYYY}` |
+| Proforma | `invoices.numbering.proforma.pattern` | `PRO {seq}/{channel}/{YYYY}` |
+| Correction | `invoices.numbering.correction.pattern` | `KOR {seq}/{channel}/{YYYY}` |
+
+### Tokens
+
+| Token | Renders |
+| --- | --- |
+| `{seq}` | the drawn sequence number |
+| `{seq:N}` | the same, zero-padded to width `N` |
+| `{channel}` | the sales channel's `code`, uppercased |
+| `{YYYY}` / `{YY}` | the issue year, 4 or 2 digits |
+| `{MM}` | the issue month |
+
+Everything else is literal text. The channel `code` is immutable and unique, so
+a number already rendered through `{channel}` can never be invalidated by a
+rename; keep a separator on both sides of it, because `FV {channel}{seq}` loses
+the boundary between two variable-length fields and renders `FV A12` for both
+(`a1`, 2) and (`a`, 12).
+
+### Three refusals, and which one is the guarantee
+
+Because the sequence is per channel and the number is not, two channels whose
+patterns can render one string are a duplicate waiting to happen. Three layers
+stand between that and a customer's document:
+
+1. **The shipped default carries `{channel}`**, so creating a sales channel
+   does not arm a collision. The system-default channel is pinned once, at boot,
+   to the historical `FV {seq}/{YYYY}` — an existing deployment's series does not
+   change shape — and only while nobody has configured the setting.
+2. **`400 INVOICE_NUMBER_PATTERN_COLLIDES`** on the settings write, naming the
+   channel the pattern collides with. It refuses a *possible* collision: at a
+   configuration write nothing is at stake, so a conservative refusal costs one
+   edit.
+3. **`409 INVOICE_NUMBER_ALREADY_ISSUED`** at issuance, naming the channel that
+   already holds the number. This is the guarantee — it is the one chokepoint
+   every number passes through — and it refuses only an *actual* duplicate. The
+   transaction rolls back, so the counter draw is undone and no gap is left.
+
+A deployment that is already configured into a collision is reported at boot,
+once per colliding pair, and is **not** blocked: a fixable invoicing
+misconfiguration must not become a storefront outage.
+
+## Extension points
+
+- **Numbering scheme** — `services/invoice-number-generator.ts` renders the
+  pattern (`formatInvoiceNumber`) and draws the sequence;
+  `services/invoice-number-collisions.ts` decides whether two channels can
+  render one string. Add a token in the first and the probe grid in the second
+  will compare it.
+- **e-invoicing** — for KSeF / Peppol / similar, plug a sender adapter
+  that consumes `invoice.issued.v1` events.
+
+## PDF templates (page builder)
+
+Admin route `/invoices/templates` edits a Puck tree of invoice sections
+(`InvoiceHeader`, `InvoiceParties`, line/VAT tables, totals, notes, KSeF,
+plus layout blocks: spacer, divider, logo, footer). Section props
+personalize typography, column visibility, and labels; missing props keep
+the historical default layout.
+
+- `GET /api/v1/admin/invoice-templates/:id/preview` — PDF of the **saved**
+  template content for that id (sample invoice fixture).
+- `POST /api/v1/admin/invoice-templates/:id/preview` — same, with a draft
+  `{ data }` body so authors can preview unsaved canvas state.
+- Runtime issue path still uses `resolveTree(salesChannelId)` (active
+  channel/global template).

package/i18n/en.json

@@ -0,0 +1,45 @@
+{
+  "settings.sellerTaxId.label": "Seller VAT / NIP",
+  "settings.sellerCompanyData.label": "Seller company data",
+  "settings.autoIssueTriggerStatus.label": "Auto-issue on order status",
+  "settings.emailSendOnIssue.label": "Email invoice on issue",
+  "settings.emailDeliveryMode.label": "Invoice email delivery mode",
+  "settings.numberingInvoicePattern.label": "Invoice numbering pattern",
+  "settings.numberingProformaPattern.label": "Proforma numbering pattern",
+  "settings.numberingCorrectionPattern.label": "Correction numbering pattern",
+  "settings.storefrontBaseUrl.label": "Storefront base URL (invoice email links)",
+  "actions.openInvoices.label": "Open invoices",
+  "actions.openInvoices.description": "View and manage issued invoices and corrections",
+  "actions.invoiceTemplates.label": "Invoice templates",
+  "actions.invoiceTemplates.description": "Customize the invoice PDF layout (WYSIWYG)",
+  "list.title": "Invoices",
+  "errors.INVOICE_NOT_READY": "The invoice for this order is not ready yet. It becomes available once it has been issued.",
+  "errors.INVOICE_NUMBER_PATTERN_COLLIDES": "This numbering pattern can produce the same document number as another sales channel. Invoice numbers must be unique across the whole platform.",
+  "errors.INVOICE_NUMBER_PATTERN_COLLIDES.other_channel": "This numbering pattern can produce the same document number as sales channel \"{channel}\". Invoice numbers are unique across the whole platform, so give this channel a pattern the other one cannot repeat — adding the channel token is the usual way.",
+  "errors.INVOICE_NUMBER_PATTERN_COLLIDES.no_sequence_token": "This numbering pattern has no sequence token, so every document in this channel would be given the same number. The field description lists the tokens you can use.",
+  "errors.INVOICE_NUMBER_ALREADY_ISSUED": "This document number is already in use. Invoice numbers are unique across the whole platform.",
+  "errors.INVOICE_NUMBER_ALREADY_ISSUED.other_channel": "Invoice number {number} is already used by sales channel \"{channel}\". Give this channel its own numbering pattern before issuing again — nothing was issued.",
+  "errors.INVOICE_NUMBER_ALREADY_ISSUED.same_channel": "Invoice number {number} has already been issued in this sales channel, so its numbering pattern is producing repeats — nothing was issued.",
+  "nav.invoices.label": "Invoices",
+  "blocks.invoiceHeader.label": "Header (number + dates)",
+  "blocks.invoiceHeader.description": "The invoice number, issue date, sale date and payment due date.",
+  "blocks.invoiceParties.label": "Seller & buyer",
+  "blocks.invoiceParties.description": "The seller and buyer details, side by side.",
+  "blocks.invoiceLineItems.label": "Line items table",
+  "blocks.invoiceLineItems.description": "The invoiced positions, as a table.",
+  "blocks.invoiceVatSummary.label": "VAT summary",
+  "blocks.invoiceVatSummary.description": "Net, VAT and gross amounts per tax rate.",
+  "blocks.invoiceTotals.label": "Totals & amount in words",
+  "blocks.invoiceTotals.description": "The invoice totals, the amount due and the amount in words.",
+  "blocks.invoiceNotes.label": "Notes (free text)",
+  "blocks.invoiceNotes.description": "Free-text notes printed on the invoice.",
+  "blocks.invoiceSpacer.label": "Spacer",
+  "blocks.invoiceSpacer.description": "Vertical whitespace between sections.",
+  "blocks.invoiceDivider.label": "Divider",
+  "blocks.invoiceDivider.description": "A horizontal rule between sections.",
+  "blocks.invoiceLogo.label": "Logo",
+  "blocks.invoiceLogo.description": "The seller logo.",
+  "blocks.invoiceFooter.label": "Footer / legal",
+  "blocks.invoiceFooter.description": "The legal footer printed at the bottom of the invoice.",
+  "blocks.category.invoice": "Invoice sections"
+}

package/i18n/pl.json

@@ -0,0 +1,45 @@
+{
+  "settings.sellerTaxId.label": "NIP / VAT sprzedawcy",
+  "settings.sellerCompanyData.label": "Dane firmy sprzedawcy",
+  "settings.autoIssueTriggerStatus.label": "Automatyczne wystawianie wg statusu zamówienia",
+  "settings.emailSendOnIssue.label": "Wyślij fakturę mailem po wystawieniu",
+  "settings.emailDeliveryMode.label": "Tryb wysyłki faktury mailem",
+  "settings.numberingInvoicePattern.label": "Format numeracji faktur",
+  "settings.numberingProformaPattern.label": "Format numeracji proform",
+  "settings.numberingCorrectionPattern.label": "Format numeracji korekt",
+  "settings.storefrontBaseUrl.label": "Bazowy URL Storefront (linki w mailach z fakturą)",
+  "actions.openInvoices.label": "Otwórz faktury",
+  "actions.openInvoices.description": "Przeglądaj i zarządzaj wystawionymi fakturami i korektami",
+  "actions.invoiceTemplates.label": "Szablony faktur",
+  "actions.invoiceTemplates.description": "Dostosuj wygląd PDF faktury (WYSIWYG)",
+  "list.title": "Faktury",
+  "errors.INVOICE_NOT_READY": "Faktura do tego zamówienia nie jest jeszcze gotowa. Będzie dostępna po jej wystawieniu.",
+  "errors.INVOICE_NUMBER_PATTERN_COLLIDES": "Ten wzorzec numeracji może wygenerować taki sam numer dokumentu jak inny kanał sprzedaży. Numery faktur muszą być unikalne w całej platformie.",
+  "errors.INVOICE_NUMBER_PATTERN_COLLIDES.other_channel": "Ten wzorzec numeracji może wygenerować taki sam numer dokumentu jak kanał sprzedaży \"{channel}\". Numery faktur są unikalne w całej platformie, więc nadaj temu kanałowi wzorzec, którego tamten nie może powtórzyć — zwykle wystarczy dodać token kanału.",
+  "errors.INVOICE_NUMBER_PATTERN_COLLIDES.no_sequence_token": "Ten wzorzec numeracji nie zawiera tokenu sekwencji, więc każdy dokument w tym kanale otrzymałby ten sam numer. Dostępne tokeny są wymienione w opisie pola.",
+  "errors.INVOICE_NUMBER_ALREADY_ISSUED": "Ten numer dokumentu jest już zajęty. Numery faktur są unikalne w całej platformie.",
+  "errors.INVOICE_NUMBER_ALREADY_ISSUED.other_channel": "Numer faktury {number} jest już używany przez kanał sprzedaży \"{channel}\". Nadaj temu kanałowi własny wzorzec numeracji przed ponowną próbą — nic nie zostało wystawione.",
+  "errors.INVOICE_NUMBER_ALREADY_ISSUED.same_channel": "Numer faktury {number} został już wystawiony w tym kanale sprzedaży, więc jego wzorzec numeracji generuje powtórzenia — nic nie zostało wystawione.",
+  "nav.invoices.label": "Faktury",
+  "blocks.invoiceHeader.label": "Nagłówek (numer i daty)",
+  "blocks.invoiceHeader.description": "Numer faktury, data wystawienia, data sprzedaży i termin płatności.",
+  "blocks.invoiceParties.label": "Sprzedawca i nabywca",
+  "blocks.invoiceParties.description": "Dane sprzedawcy i nabywcy obok siebie.",
+  "blocks.invoiceLineItems.label": "Tabela pozycji",
+  "blocks.invoiceLineItems.description": "Pozycje faktury w postaci tabeli.",
+  "blocks.invoiceVatSummary.label": "Podsumowanie VAT",
+  "blocks.invoiceVatSummary.description": "Kwoty netto, VAT i brutto w podziale na stawki podatku.",
+  "blocks.invoiceTotals.label": "Sumy i kwota słownie",
+  "blocks.invoiceTotals.description": "Sumy faktury, kwota do zapłaty i kwota słownie.",
+  "blocks.invoiceNotes.label": "Uwagi (tekst dowolny)",
+  "blocks.invoiceNotes.description": "Uwagi w postaci dowolnego tekstu drukowane na fakturze.",
+  "blocks.invoiceSpacer.label": "Odstęp",
+  "blocks.invoiceSpacer.description": "Pionowy odstęp pomiędzy sekcjami.",
+  "blocks.invoiceDivider.label": "Separator",
+  "blocks.invoiceDivider.description": "Linia pozioma pomiędzy sekcjami.",
+  "blocks.invoiceLogo.label": "Logo",
+  "blocks.invoiceLogo.description": "Logo sprzedawcy.",
+  "blocks.invoiceFooter.label": "Stopka / informacje prawne",
+  "blocks.invoiceFooter.description": "Stopka prawna drukowana na dole faktury.",
+  "blocks.category.invoice": "Sekcje faktury"
+}

package/package.json

@@ -1,6 +1,122 @@
 {
   "name": "@endora-commerce/mod-invoices",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Invoice generation, numbering, PDF templates, corrections, and email delivery.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "invoices"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/invoices"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./backend": {
+      "types": "./dist/backend/index.d.ts",
+      "default": "./dist/backend/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "default": "./dist/migrations/index.js"
+    },
+    "./ports": {
+      "types": "./dist/ports/index.d.ts",
+      "default": "./dist/ports/index.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    },
+    "./tailwind.css": "./tailwind.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "i18n",
+    "docs",
+    "tailwind.css"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@measured/puck": "^0",
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/migrations": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "@types/pdfmake": "^0",
+    "fastify": "^5",
+    "lucide-react": "^1",
+    "pdfmake": "^0",
+    "react": "^19",
+    "react-router-dom": "^7",
+    "zod": "^4",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/email-components": "0.100.0",
+    "@endora-commerce/page-builder-admin": "0.100.0",
+    "@endora-commerce/page-builder-core": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "peerDependenciesMeta": {
+    "@endora-commerce/admin-kit": {
+      "optional": true
+    },
+    "@endora-commerce/page-builder-admin": {
+      "optional": true
+    },
+    "@measured/puck": {
+      "optional": true
+    },
+    "lucide-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-router-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@fastify/type-provider-zod": "^1.0.0",
+    "@measured/puck": "^0.20.2",
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/migrations": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "@types/pdfmake": "^0.3.2",
+    "@types/react": "^19.2.14",
+    "fastify": "^5.12.5",
+    "lucide-react": "^1.11.0",
+    "pdfmake": "^0.3.7",
+    "react": "^19.2.5",
+    "react-router-dom": "^7.18.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.2.0",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/email-components": "0.100.0",
+    "@endora-commerce/page-builder-admin": "0.100.0",
+    "@endora-commerce/page-builder-core": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.ui.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.ui.json --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
 }

package/tailwind.css

@@ -0,0 +1,14 @@
+/* @endora-commerce/mod-invoices — AUTO-GENERATED by `pnpm --filter backend run manifests:generate`.
+ *
+ * The `@source` directives this package asks its host to scan
+ * (`specs/110-instance-repository/contracts/admin-stylesheet-composition.md` R1).
+ * They resolve relative to **this file**, so they hold wherever the package is
+ * installed — a workspace link here, `node_modules` in a client's instance.
+ *
+ * The `dist` line is what a published tarball ships and is what an instance
+ * scans; the `src` line is inert there and is what keeps `pnpm --filter admin
+ * run dev` reading source in this repository. Do not edit: run
+ * `pnpm --filter backend run manifests:generate`.
+ */
+@source "./dist/admin";
+@source "./src/admin";