The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
docs: rewrite architecture page with package map and illustrations (#1679)
Viktor Holikd89ce57d981d
diff --git a/.claude/skills/mercur-figure/SKILL.md b/.claude/skills/mercur-figure/SKILL.mdnew file mode 100644index 000000000..4d37b1d1e--- /dev/null+++ b/.claude/skills/mercur-figure/SKILL.md@@ -0,0 +1,80 @@+---+name: mercur-figure+description: Draw a Mercur docs illustration — a hairline, monospace fragment of Mercur's own UI (stacked panels, tabs, tables, square status markers, quiet tiled background) rendered as a light and a dark SVG for apps/docs. Use when the user asks for an illustration, figure, diagram, or hero image for a docs page (e.g. "illustrate the architecture page", "replace this mermaid diagram", "make a figure like Infisical's / Hairline's"), or wants an existing figure in apps/docs/figures changed.+argument-hint: "[page or idea]"+---++# mercur-figure — docs illustrations++A Mercur figure is a fragment of a real Mercur screen, drawn with 1px lines in one+monospace face: panels stacked like paper, tabs, a table with real data, square+status markers, and a few quiet tiles behind it. It explains one idea by+*showing the product doing it*, not by drawing boxes and arrows.++Lineage: the cascading panels of infisical.com, the mono order-group table of+the Mercur admin, and the discipline of [Hairline](https://hairline.lucasmarkes.com)+(one stroke weight, colour as information, a designed still frame, no+decoration). The figures are static SVG — no motion — so they work as `<img>`+in Mintlify and in both themes.++## Files++| File | Role |+| --- | --- |+| `kit.mjs` | The drawing kit. Tokens for both themes, every primitive. **Do not add colours or sizes outside it.** |+| `build.mjs` | Renders a figure to `<name>-light.svg` / `<name>-dark.svg`, checks it, prints the MDX snippet, `--look` writes PNGs. |+| `references/rules.md` | The ten rules. A figure that breaks one is not finished. |+| `references/kit.md` | The kit API with examples. |+| `apps/docs/figures/*.mjs` | Figure sources (one per figure). These are the worked examples — read the nearest before writing a new one. |+| `apps/docs/images/figures/*.svg` | Build output, committed. Never hand-edit. |++## Workflow++1. **Read the page.** Find the one idea the figure must carry (a section, or a+ mermaid block to replace). One figure, one idea.+2. **Concept.** Offer two or three one-liners, then wait for a pick (if nobody+ can answer, take the one with the strongest still frame and say so):+ > **Name.** Which Mercur surface it shows · what data is on it · what the eye lands on first (the accent).++ Prefer a *screen* over a diagram: "the Orders list showing group #G98 split+ into two seller orders" beats "cart → arrow → orders". Use a diagram layout+ (panels + wires) only when the idea is genuinely topology (layers, request+ paths), and even then make every box a little UI panel with real content.+3. **Gather real data.** Every name in the figure must exist: route paths,+ workflow + hook names, widget zone ids, block names, module names, statuses.+ Grep the repo (`packages/core/src/workflows`, `packages/registry`,+ `packages/vendor/src` for zone ids). Plausible values (order numbers,+ amounts, store names) must add up — group totals equal the sum of their+ orders, commission + payout equal total.+4. **Write** `apps/docs/figures/<name>.mjs` — `export default { name, width,+ height, alt, draw(f) }`, using only the kit (`references/kit.md`). Width is+ 1040 unless there is a reason.+5. **Build and look**:+ ```bash+ node .claude/skills/mercur-figure/build.mjs apps/docs/figures/<name>.mjs --look <scratchpad>/look+ ```+ Exit 0 = clean, 1 = rejected, 3 = warnings (overflowing cells, small text,+ too much accent). Fix every warning. Then **Read both PNGs** and answer the+ look checklist in `references/rules.md`. Do not claim it is done without+ looking at both themes.+6. **Place it** in the MDX with the snippet `build.mjs` prints (two `<img>`+ tags with `dark:hidden` / `hidden dark:block`). Put the figure directly+ under the heading or paragraph it illustrates; keep the `alt` a full+ sentence describing what the figure shows.+7. **Hand over**: the figure(s), the concept in one line each, what was+ verified (build exit code, both themes looked at), and anything not checked+ (e.g. not viewed inside `mint dev`).++## What goes wrong++| If you catch yourself | Do this instead |+| --- | --- |+| writing `<rect>`, a hex colour, or a font size in a figure | use the kit; a missing primitive goes into `kit.mjs` with tokens for both themes |+| drawing arrows with labels on them | wires carry no words; the panels they connect say what flows |+| colouring a header marker because it looks nice | markers are `hi`/`mid`/`lo` unless the colour means something (status, the accent) |+| making two things violet | violet marks the one place the figure is about (rule 4) |+| lorem ipsum, `foo`, `example-1` | real names from the repo, plausible values that add up |+| a table so wide the text overflows | shorten the value (`/vendor/sellers/…`) or the column set; never shrink the font |+| shrinking text to fit | text below 14px at 1040 wide is unreadable in the docs column; cut content instead |+| filling the canvas with tiles | tiles are ambience at the edges; `clear` them out of wire corridors |+| hand-editing the SVG output | edit the `.mjs`, rebuild |diff --git a/.claude/skills/mercur-figure/build.mjs b/.claude/skills/mercur-figure/build.mjsnew file mode 100644index 000000000..aeb25f83a--- /dev/null+++ b/.claude/skills/mercur-figure/build.mjs@@ -0,0 +1,75 @@+#!/usr/bin/env node+// node build.mjs <figure.mjs> [--out <dir>] [--look <dir>] [--width 720]+//+// Renders the figure in both themes to <out>/<name>-light.svg and+// <name>-dark.svg, checks it, and with --look also writes PNGs of each theme+// on the docs page colour at the width the docs show it.++import { execFileSync } from "node:child_process"+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"+import { basename, resolve } from "node:path"+import { pathToFileURL } from "node:url"+import { Figure } from "./kit.mjs"++const PAGE = { light: "#ffffff", dark: "#0c0a12" }++const args = process.argv.slice(2)+const file = args.find((a) => !a.startsWith("--") && !args[args.indexOf(a) - 1]?.startsWith("--"))+const opt = (k, d) => (args.includes(k) ? args[args.indexOf(k) + 1] : d)++if (!file) {+ console.error("usage: node build.mjs <figure.mjs> [--out <dir>] [--look <dir>] [--width 720]")+ process.exit(2)+}++const out = resolve(opt("--out", "apps/docs/images/figures"))+const look = args.includes("--look") ? resolve(opt("--look")) : null+const lookWidth = Number(opt("--width", 720))++const source = readFileSync(file, "utf8")+const spec = (await import(pathToFileURL(resolve(file)).href)).default+const failures = []++for (const k of ["name", "width", "height", "alt", "draw"])+ if (spec[k] === undefined) failures.push(`figure is missing "${k}"`)+if (spec.name && !/^[a-z0-9-]+$/.test(spec.name)) failures.push(`name "${spec.name}" is not kebab-case`)+if (/['"`]#[0-9a-f]{6}([0-9a-f]{2})?['"`]/i.test(source))+ failures.push("figure source holds a raw hex colour; use a tone (hi/text/mid/lo/green/red/amber/violet)")+if (/<\s*(rect|text|path|svg|g)\b/.test(source)) failures.push("figure source writes SVG markup; use the kit")+if (failures.length) {+ failures.forEach((f) => console.error(`FAIL ${f}`))+ process.exit(1)+}++mkdirSync(out, { recursive: true })+if (look) mkdirSync(look, { recursive: true })++const warnings = new Set()+let accent = 0+for (const theme of ["light", "dark"]) {+ const fig = new Figure({ name: spec.name, width: spec.width, height: spec.height, alt: spec.alt, theme })+ spec.draw(fig)+ fig.warnings.forEach((w) => warnings.add(w))+ accent = fig.stats.accent+ const svgPath = `${out}/${spec.name}-${theme}.svg`+ writeFileSync(svgPath, fig.svg())+ console.log(`wrote ${svgPath}`)+ if (look) {+ const png = `${look}/${spec.name}-${theme}.png`+ try {+ execFileSync("rsvg-convert", ["-w", String(lookWidth * 2), "-b", PAGE[theme], "-o", png, svgPath])+ console.log(`look ${png}`)+ } catch {+ console.error("look rsvg-convert not found (brew install librsvg); open the SVGs in a browser instead")+ }+ }+}++if (accent > 4) warnings.add(`violet used ${accent} times; the accent marks one place (rule 4)`)+warnings.forEach((w) => console.log(`WARN ${w}`))++const rel = (p) => p.replace(/^.*\/apps\/docs/, "")+console.log(`+<img className="block dark:hidden" src="${rel(`${out}/${spec.name}-light.svg`)}" alt="${spec.alt}" />+<img className="hidden dark:block" src="${rel(`${out}/${spec.name}-dark.svg`)}" alt="${spec.alt}" />`)+process.exit(warnings.size ? 3 : 0)diff --git a/.claude/skills/mercur-figure/kit.mjs b/.claude/skills/mercur-figure/kit.mjsnew file mode 100644index 000000000..315db72b5--- /dev/null+++ b/.claude/skills/mercur-figure/kit.mjs@@ -0,0 +1,383 @@+// Drawing kit for Mercur docs figures. Figures call into a Figure; they never+// write SVG, colours or font sizes of their own.++export const FONT =+ "JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace"++export const SIZE = { title: 18, tab: 17, body: 16, cell: 15, caps: 14 }+const CAPS_TRACK = 1.2+export const MIN_TEXT = 14++export const THEMES = {+ light: {+ plate: "#ffffff",+ line: "#e4e4e7",+ rule: "#ededf0",+ wire: "#c4c4cc",+ hi: "#18181b",+ text: "#3f3f46",+ mid: "#71717a",+ lo: "#a1a1aa",+ tile: "#ececef",+ dot: "#d9d9de",+ grain: "#e4e4e7",+ tagBg: "#f4f4f5",+ toggleOff: "#d4d4d8",+ shadow: "#18181b",+ shadowOpacity: 0.07,+ grainOpacity: 0.22,+ green: "#3f7d3a",+ red: "#b3361f",+ amber: "#c2680c",+ violet: "#7c3aed",+ },+ dark: {+ plate: "#15121d",+ line: "#2b2636",+ rule: "#221e2b",+ wire: "#3d3749",+ hi: "#f4f4f5",+ text: "#d4d4d8",+ mid: "#a1a1aa",+ lo: "#71717a",+ tile: "#1d1926",+ dot: "#2c2737",+ grain: "#1d1926",+ tagBg: "#1f1b29",+ toggleOff: "#3f3a4b",+ shadow: "#000000",+ shadowOpacity: 0.55,+ grainOpacity: 0.35,+ green: "#6fbf68",+ red: "#f0735a",+ amber: "#f2a14b",+ violet: "#a78bfa",+ },+}++const TONES = ["hi", "text", "mid", "lo", "green", "red", "amber", "violet"]++const esc = (s) =>+ String(s).replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">")++export const measure = (s, size = SIZE.body, track = 0) =>+ String(s).length * (size * 0.6 + track)++const r1 = (n) => Math.round(n * 10) / 10++function rng(seed) {+ let a = seed >>> 0+ return () => {+ a = (a + 0x6d2b79f5) >>> 0+ let t = a+ t = Math.imul(t ^ (t >>> 15), t | 1)+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61)+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296+ }+}++class Layer {+ constructor(fig, w, h, where) {+ this.fig = fig+ this.t = fig.t+ this.w = w+ this.h = h+ this.where = where+ this.out = []+ }++ color(tone) {+ if (!TONES.includes(tone)) throw new Error(`unknown tone "${tone}"`)+ if (tone === "violet") this.fig.stats.accent+++ return this.t[tone]+ }++ rect(x, y, w, h, { fill = "none", stroke, dash } = {}) {+ const s = stroke ? ` stroke="${stroke}" stroke-width="1"` : ""+ const d = dash ? ` stroke-dasharray="${dash}"` : ""+ this.out.push(+ `<rect x="${r1(x)}" y="${r1(y)}" width="${r1(w)}" height="${r1(h)}" fill="${fill}"${s}${d}/>`+ )+ }++ line(x1, y1, x2, y2, { stroke = this.t.line, dash } = {}) {+ const d = dash ? ` stroke-dasharray="${dash}"` : ""+ this.out.push(+ `<line x1="${r1(x1)}" y1="${r1(y1)}" x2="${r1(x2)}" y2="${r1(y2)}" stroke="${stroke}" stroke-width="1"${d}/>`+ )+ }++ text(x, y, str, { size = SIZE.body, tone = "text", weight, anchor, caps } = {}) {+ if (size < MIN_TEXT) this.fig.warn(`text "${str}" is ${size}px, below ${MIN_TEXT}`)+ const s = caps ? String(str).toUpperCase() : String(str)+ const attrs = [+ `x="${r1(x)}"`,+ `y="${r1(y)}"`,+ `font-size="${size}"`,+ `fill="${this.color(tone)}"`,+ ]+ if (caps) attrs.push(`letter-spacing="${CAPS_TRACK}"`)+ if (weight) attrs.push(`font-weight="${weight}"`)+ if (anchor) attrs.push(`text-anchor="${anchor}"`)+ this.out.push(`<text ${attrs.join(" ")}>${esc(s)}</text>`)+ return measure(s, size, caps ? CAPS_TRACK : 0)+ }++ // Text vertically centred on `mid`.+ label(x, mid, str, opts = {}) {+ const size = opts.size ?? SIZE.body+ return this.text(x, mid + size * 0.35, str, opts)+ }++ marker(x, mid, tone, size = 10) {+ this.rect(x, mid - size / 2, size, size, { fill: this.color(tone) })+ return size+ }++ tag(x, mid, str, { dashed = false, tone = "mid", size = SIZE.cell } = {}) {+ const w = measure(str, size) + 24+ const h = 30+ if (dashed) this.rect(x + 0.5, mid - h / 2 + 0.5, w - 1, h - 1, { stroke: this.t.wire, dash: "3 3" })+ else this.rect(x, mid - h / 2, w, h, { fill: this.t.tagBg })+ this.label(x + 12, mid, str, { size, tone })+ return w+ }++ chip(x, mid, str, tone, { align = "left" } = {}) {+ const w = 12 + 10 + 10 + measure(str.toUpperCase(), SIZE.caps, CAPS_TRACK) + 12+ const x0 = align === "right" ? x - w : x+ this.rect(x0, mid - 16, w, 32, { fill: this.t.tagBg })+ this.marker(x0 + 12, mid, tone)+ this.label(x0 + 34, mid, str, { size: SIZE.caps, tone: "text", caps: true })+ return w+ }++ toggle(x, mid, on, tone = "green") {+ this.rect(x, mid - 11, 46, 22, { fill: on ? this.color(tone) : this.t.toggleOff })+ this.rect(on ? x + 24 : x + 3, mid - 8, 19, 16, { fill: this.t.plate })+ return 46+ }++ caret(x, mid, open, tone = "text") {+ const c = this.color(tone)+ const pts = open+ ? `${x},${mid - 3.5} ${x + 10},${mid - 3.5} ${x + 5},${mid + 3.5}`+ : `${x + 2},${mid - 5} ${x + 9},${mid} ${x + 2},${mid + 5}`+ this.out.push(`<polygon points="${pts}" fill="${c}"/>`)+ return 10+ }++ // A panel's title bar: marker, title, divider, tabs, and one control on the right.+ header({ h = 76, marker, title, tabs = [], active = 0, toggle, note, pad = 24 }) {+ const mid = h / 2+ let x = pad+ if (marker) x += this.marker(x, mid, marker) + 12+ x += this.label(x, mid, title, { size: SIZE.title, tone: "hi", weight: 500 })+ if (tabs.length) {+ x += 24+ this.line(x, mid - 18, x, mid + 18)+ x += 32+ tabs.forEach((tab, i) => {+ const on = i === active+ const tw = this.label(x, mid, tab, { size: SIZE.tab, tone: on ? "hi" : "mid" })+ if (on) this.rect(x - 18, h - 3, tw + 36, 3, { fill: this.t.hi })+ x += tw + 40+ })+ }+ if (toggle) {+ const lw = measure(toggle.label, SIZE.cell)+ const lx = this.w - pad - lw+ this.label(lx, mid, toggle.label, { size: SIZE.cell, tone: "text" })+ this.toggle(lx - 14 - 46, mid, toggle.on, toggle.tone)+ } else if (note) {+ this.label(this.w - pad, mid, note, { size: SIZE.cell, tone: "lo", anchor: "end" })+ }+ this.line(0, h, this.w, h)+ return h+ }++ cell(x, mid, colW, spec, align) {+ if (spec == null || spec === "") return+ const s = typeof spec === "string" ? { text: spec } : spec+ let used = 0+ let cx = x+ if (s.indent) cx += s.indent+ if (s.caret !== undefined) {+ this.caret(cx, mid, s.caret)+ cx += 22+ }+ if (s.marker) cx += this.marker(cx, mid, s.marker) + 12+ if (s.chip) {+ used = this.chip(align === "right" ? x + colW : cx, mid, s.chip, s.tone ?? "green", { align })+ } else if (s.tag) {+ used = this.tag(cx, mid, s.tag, { dashed: s.dashed })+ } else if (s.toggle !== undefined) {+ used = this.toggle(align === "right" ? x + colW - 46 : cx, mid, s.toggle, s.tone)+ } else if (s.text !== undefined) {+ const opts = { size: SIZE.body, tone: s.tone ?? "hi" }+ used =+ align === "right"+ ? this.label(x + colW, mid, s.text, { ...opts, anchor: "end" })+ : this.label(cx, mid, s.text, opts)+ }+ if (cx - x + used > colW + 1)+ this.fig.warn(`cell "${s.text ?? s.tag ?? s.chip}" overflows its ${colW}px column in ${this.where}`)+ }++ // columns: [{ label, w, align }]. rows: arrays of cells, or { cells, accent }.+ table({ y = 0, columns, rows, rowH = 64, headH = 54, pad = 32 }) {+ const xs = []+ let x = pad+ for (const c of columns) {+ xs.push(x)+ x += c.w+ }+ if (x > this.w - pad + 1 && !this.allowBleed)+ this.fig.warn(`table columns (${x + pad}px) are wider than ${this.where} (${this.w}px)`)+ columns.forEach((c, i) => {+ if (!c.label) return+ const lx = c.align === "right" ? xs[i] + c.w : xs[i]+ this.label(lx, y + headH / 2, c.label, {+ size: SIZE.caps,+ tone: "mid",+ caps: true,+ anchor: c.align === "right" ? "end" : undefined,+ })+ })+ this.line(0, y + headH, this.w, y + headH, { stroke: this.t.rule })+ let ry = y + headH+ for (const row of rows) {+ const r = Array.isArray(row) ? { cells: row } : row+ if (r.accent) this.rect(0, ry, 3, rowH, { fill: this.color("violet") })+ r.cells.forEach((spec, i) => this.cell(xs[i], ry + rowH / 2, columns[i].w, spec, columns[i].align))+ ry += rowH+ this.line(0, ry, this.w, ry, { stroke: this.t.rule })+ }+ return ry+ }++ // A row of tags that wraps inside [x, x + w]. Returns the bottom y.+ tags(x, y, w, items, { gap = 10, lineH = 42 } = {}) {+ let cx = x+ let cy = y + lineH / 2+ for (const it of items) {+ const s = typeof it === "string" ? { tag: it } : it+ const tw = measure(s.tag, SIZE.cell) + 24+ if (cx + tw > x + w && cx > x) {+ cx = x+ cy += lineH+ }+ this.tag(cx, cy, s.tag, { dashed: s.dashed, tone: s.tone })+ cx += tw + gap+ }+ return cy + lineH / 2+ }+}++export class Figure extends Layer {+ constructor({ name, width, height, theme, alt }) {+ const t = THEMES[theme]+ super({ t, stats: { accent: 0 } }, width, height, name)+ this.fig = this+ this.t = t+ this.name = name+ this.alt = alt+ this.theme = theme+ this.stats = { accent: 0 }+ this.warnings = []+ this.defs = []+ this.ids = 0+ this.defs.push(+ `<filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="${t.shadow}" flood-opacity="${t.shadowOpacity}"/></filter>`,+ `<filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter>`,+ `<pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="${t.dot}"/></pattern>`+ )+ }++ warn(msg) {+ if (!this.warnings.includes(msg)) this.warnings.push(msg)+ }++ // Quiet background tiles, denser toward the edges of the canvas. `clear`+ // lists rects (wire corridors, gaps between panels) no tile may touch.+ // Tiles always paint first, so call this last, once the layout is known.+ tiles({ seed = 1, size = 88, density = 0.28, ox = 0, oy = 0, clear = [] } = {}) {+ const rand = rng(seed)+ const drawn = this.out+ this.out = []+ const cols = Math.ceil((this.w - ox) / size) + 1+ const rows = Math.ceil((this.h - oy) / size) + 1+ for (let j = -1; j < rows; j++) {+ for (let i = -1; i < cols; i++) {+ const x = ox + i * size+ const y = oy + j * size+ const ex = Math.abs((x + size / 2) / this.w - 0.5) * 2+ const ey = Math.abs((y + size / 2) / this.h - 0.5) * 2+ const edge = Math.max(ex, ey)+ if (rand() > density * (0.25 + edge)) continue+ const k = rand()+ if (clear.some((c) => x < c.x + c.w && x + size > c.x && y < c.y + c.h && y + size > c.y)) continue+ if (k < 0.45) this.rect(x + 0.5, y + 0.5, size - 1, size - 1, { stroke: this.t.tile })+ else if (k < 0.8) this.rect(x, y, size, size, { fill: "url(#dt)" })+ else {+ this.rect(x, y, size, size, { fill: this.t.grain })+ this.out.push(+ `<rect x="${x}" y="${y}" width="${size}" height="${size}" fill="${this.t.mid}" opacity="${this.t.grainOpacity}" filter="url(#gr)"/>`+ )+ }+ }+ }+ this.out = this.out.concat(drawn)+ }++ // An opaque plate. `draw` gets a layer whose origin is the panel's top-left+ // and whose drawing is clipped to the panel. Without `h`, the panel is as+ // tall as the y that `draw` returns.+ panel({ x, y, w, h, shadow = true, name = "panel", bleed = false }, draw) {+ const id = `c${++this.ids}`+ const p = new Layer(this, w, h ?? Infinity, name)+ p.allowBleed = bleed+ const H = h ?? draw?.(p)+ if (h !== undefined) draw?.(p)+ if (typeof H !== "number") throw new Error(`${name}: give it an h, or return the bottom y from draw`)+ p.h = H+ this.defs.push(`<clipPath id="${id}"><rect x="0" y="0" width="${w}" height="${H}"/></clipPath>`)+ if (shadow)+ this.out.push(`<rect x="${x}" y="${y}" width="${w}" height="${H}" fill="${this.t.plate}" filter="url(#sh)"/>`)+ this.out.push(`<rect x="${x}" y="${y}" width="${w}" height="${H}" fill="${this.t.plate}"/>`)+ this.out.push(+ `<g transform="translate(${x} ${y})"><g clip-path="url(#${id})">${p.out.join("")}</g></g>`+ )+ this.rect(x + 0.5, y + 0.5, w - 1, H - 1, { stroke: this.t.line })+ return { x, y, w, h: H }+ }++ // Back-to-front stack of panels, each one step further down-left.+ cascade({ x, y, w, h, dx = -60, dy = 86 }, panels) {+ panels.forEach((draw, i) => {+ const n = panels.length - 1 - i+ this.panel({ x: x - n * dx, y: y - n * dy, w, h, name: `cascade ${i}`, bleed: true }, draw)+ })+ }++ // An orthogonal connector ending in a small square.+ wire(points, { dash, end = true } = {}) {+ const d = points.map(([px, py], i) => `${i ? "L" : "M"}${r1(px)} ${r1(py)}`).join(" ")+ const da = dash ? ` stroke-dasharray="${dash}"` : ""+ this.out.push(`<path d="${d}" fill="none" stroke="${this.t.wire}" stroke-width="1"${da}/>`)+ if (end) {+ const [ex, ey] = points[points.length - 1]+ this.rect(ex - 3, ey - 3, 6, 6, { fill: this.t.wire })+ }+ }++ svg() {+ return [+ `<svg xmlns="http://www.w3.org/2000/svg" width="${this.w}" height="${this.h}" viewBox="0 0 ${this.w} ${this.h}" font-family="${FONT}" role="img" aria-label="${esc(this.alt)}">`,+ `<title>${esc(this.alt)}</title>`,+ `<defs>${this.defs.join("")}</defs>`,+ this.out.join(""),+ `</svg>`,+ ].join("\n")+ }+}diff --git a/.claude/skills/mercur-figure/references/kit.md b/.claude/skills/mercur-figure/references/kit.mdnew file mode 100644index 000000000..995d8913b--- /dev/null+++ b/.claude/skills/mercur-figure/references/kit.md@@ -0,0 +1,73 @@+# Kit API++A figure is a module:++```js+export default {+ name: "order-split", // kebab-case; output file stem+ width: 1040, // viewBox width; keep 1040+ height: 610, // tighten after the first look+ alt: "One sentence that says what the figure shows.",+ draw(f) { /* f is a Figure */ },+}+```++`draw` runs once per theme. Never branch on the theme; tokens do that.++## Tones++Every colour is a tone: `hi` `text` `mid` `lo` (greys, strongest to faintest),+`green` `amber` `red` (status), `violet` (the accent). Structural colours+(`plate`, `line`, `rule`, `wire`, `tagBg`) are applied by the primitives; read+them as `f.t.rule` only when passing a stroke to `line`.++## Figure (canvas)++| Call | Draws |+| --- | --- |+| `f.tiles({ seed, size = 88, density = .28, clear = [] })` | background tiles; they always paint first, so call last with the real wire corridors in `clear` |+| `f.panel({ x, y, w, h?, shadow = true, name }, (p) => …)` | an opaque, clipped, shadowed plate; `p` has origin at the panel's top-left. Omit `h` and return the bottom y from the callback to size it to content. Returns `{ x, y, w, h }`. |+| `f.cascade({ x, y, w, h, dx = -60, dy = 86 }, [draw, …])` | panels back → front; the last is the front one at `(x, y)`, each earlier one `-dx` right and `dy` up |+| `f.wire([[x, y], …], { end = true, dash })` | orthogonal connector ending in a square |++## Layer (inside a panel, also on `f`)++| Call | Returns | Draws |+| --- | --- | --- |+| `p.header({ h = 76, marker, title, tabs, active = 0, toggle: { on, label, tone }, note, pad = 24 })` | h | title bar: marker, title, divider, tabs with the active bar, a toggle or a faint note on the right, bottom border |+| `p.table({ y, columns: [{ label, w, align }], rows, rowH = 64, headH = 54, pad = 32 })` | bottom y | caps column heads and rows; columns should sum to `p.w - 2 * pad` |+| `p.tags(x, y, w, items)` | bottom y | wrapping row of tags; items are strings or `{ tag, dashed }` |+| `p.label(x, mid, str, { size, tone, weight, anchor, caps })` | width | text vertically centred on `mid` |+| `p.text(x, baseline, str, opts)` | width | text on a baseline |+| `p.marker(x, mid, tone, size = 10)` | size | square marker |+| `p.tag(x, mid, str, { dashed })` | width | grey (or dashed = "yours to add") pill |+| `p.chip(x, mid, str, tone, { align })` | width | status: square marker + caps label on grey |+| `p.toggle(x, mid, on, tone = "green")` | 46 | square switch |+| `p.caret(x, mid, open)` | 10 | ▾ / ▸ for expandable rows |+| `p.line(x1, y1, x2, y2, { stroke, dash })` | | a 1px line |+| `p.rect(x, y, w, h, { fill, stroke, dash })` | | a raw rect — prefer the primitives above |++## Table cells++A row is an array of cells, or `{ accent: true, cells }` for the one accented+row (violet bar on the left). A cell is:++| Cell | Renders |+| --- | --- |+| `"text"` | body text, `hi` |+| `{ text, tone }` | body text in a tone (`mid` for secondary numbers, `text` for paths) |+| `{ indent: 32, text }` | a child row's first cell |+| `{ caret: true \| false, text }` | an expandable group row |+| `{ marker: tone, text }` | marker then text |+| `{ tag, dashed }` | a pill |+| `{ chip, tone }` | a status chip |+| `{ toggle: bool, tone }` | a switch |++`align: "right"` on a column right-aligns text, chips and toggles (use it for+money and for the last column of back panels, so their cropped tail shows).++## Measuring++Everything is monospace: a string is `length × size × 0.6` wide (`measure` in+`kit.mjs`; caps add 1.2 per character). Lay out with arithmetic, not guesses —+and let `build.mjs` warn you about overflow.diff --git a/.claude/skills/mercur-figure/references/rules.md b/.claude/skills/mercur-figure/references/rules.mdnew file mode 100644index 000000000..96e55f276--- /dev/null+++ b/.claude/skills/mercur-figure/references/rules.md@@ -0,0 +1,117 @@+# The ten rules++Adapted for static docs figures from Hairline's ten rules+(hairline.lucasmarkes.com, MIT) and the Infisical marketing illustrations.++## 01 · real: it is a Mercur screen++Every panel is a fragment of a real Mercur surface — admin, vendor, a cart, a+route table, a file tree — with real names from the codebase. Values may be+invented but must be plausible and consistent (sums add up, ids look like ids).++- **Rejected when:** a name does not exist in the repo; numbers contradict each+ other; placeholder text appears.++## 02 · mono: one face, four sizes++Everything is set in the kit's monospace stack at the kit's sizes: title 18,+tab 17, body 16, cell 15, caps 14 (uppercase, tracked). Nothing under 14 at+1040 wide — the docs column shows figures at ~720px, so 14 becomes ~10px.++- **Rejected when:** a size outside the scale; bold anywhere but a title or a+ surface path (weight 500); text overflowing its column.++## 03 · hairline: one stroke weight, square corners++All lines are 1px. Corners are square (the docs use `border-radius: 0`). Plates+are opaque and filled with the plate colour; a panel is a plate, a 1px border,+and rules between rows. Rules inside a panel are lighter (`rule`) than its+border (`line`).++- **Rejected when:** a rounded corner, a thicker line used for emphasis (the+ only exceptions are the 3px active-tab bar and the 3px accent bar).++## 04 · accent: colour is information++Structure is grey. Colour appears only where it means something:++- **status** — `green` done/on, `amber` pending/diff, `red` failing/not done,+ always as a small square marker (chips, header markers) or a toggle track;+- **the accent** — `violet`, Mercur's colour, marks the one place the figure is+ about: one header marker, one accented row, one domain. One idea, one place.++Text is never coloured. `build.mjs` warns when violet is used more than four+times.++- **Rejected when:** two unrelated things are violet; a colour is decorative; a+ status colour contradicts its label.++## 05 · rest: the still frame is composed++The figure is a thumbnail. Something is clearly in front, something recedes,+and the eye lands on the accent first. Stacks cascade down-left (`cascade`) so+the front panel is the one with the story and the panels behind show only a+header and a cropped column tail.++- **Rejected when:** everything has the same weight; the front panel is not the+ one the caption is about; the composition is a regular grid of equal boxes+ with nothing leading.++## 06 · honest: back to front++Draw in paint order: tiles, wires, then panels from the back. Plates hide what+is behind them; a wire may end under a plate (its square half-hidden), never+cross over a panel's face.++- **Rejected when:** a line shows through a plate; a wire crosses a panel.++## 07 · crop: cut, don't shrink++Panels behind the front one are cut by it, and their content is cut by their+own edges (`panel` clips). A cropped column tail (`.00`, `ICE`) says "there is+more" better than a shrunken full table.++- **Rejected when:** a back panel was squeezed to fit; content spills outside+ its panel.++## 08 · quiet: tiles are ambience++The background is a sparse grid of 88px tiles — outlined squares, dotted+squares, a few grain blocks — denser toward the canvas edges. They sit behind+everything and never read as content.++- **Keep it:** `f.tiles({ seed, clear })` last (it paints underneath); pass `clear` rects for wire+ corridors so a tile edge never looks like a wire. Change `seed` until the+ edges look balanced.+- **Rejected when:** a tile edge lines up with or continues a wire; tiles crowd+ the centre.++## 09 · wires: orthogonal, few, unlabelled++Only topology figures have wires. They run vertical–horizontal–vertical, merge+rather than cross, and end in a 6px square. They carry no labels; the panels at+each end say what connects.++- **Rejected when:** wires cross; a diagonal; an arrowhead; a label on a wire.++## 10 · both themes++The same figure ships as `-light.svg` and `-dark.svg`. The dark plate is the+docs' lifted surface (`#15121d`) on the page's `#0c0a12`; nothing may vanish+or invert meaning between them.++- **Rejected when:** only one theme was looked at; an element disappears in+ one theme.++## The look++After every build, Read both PNGs and answer yes/no:++1. At 720px wide, can you read every word?+2. Does the eye land on the accent first?+3. Is every name real, and do the numbers add up?+4. Is there exactly one violet place?+5. Do the panels behind read as "more of the product", not as clutter?+6. No overflowing text, no tile posing as a wire, no wire crossing a panel?+7. Does the dark one hold up as well as the light one?+8. Without the caption, would someone who knows the page say what it shows?diff --git a/apps/docs/figures/architecture-layers.mjs b/apps/docs/figures/architecture-layers.mjsnew file mode 100644index 000000000..4cc5e104c--- /dev/null+++ b/apps/docs/figures/architecture-layers.mjs@@ -0,0 +1,134 @@+const CLIENTS = [+ ["Admin", "@mercurjs/admin", "dashboard-sdk"],+ ["Vendor", "@mercurjs/vendor", "dashboard-sdk"],+ ["Storefront", "Next.js or any", "framework"],+ ["Services", "ERP · PIM", "AI agents"],+]++const SURFACES = [+ ["/admin/*", "role-gated"],+ ["/vendor/*", "seller-scoped"],+ ["/store/*", "public"],+]++const DOMAINS = [+ {+ label: "Marketplace",+ sub: "@mercurjs/core",+ marker: "violet",+ tags: ["seller", "offer", "commission", "payout", "product-edit", "product-attribute", "review", "custom-fields"],+ },+ {+ label: "Commerce",+ sub: "@medusajs/medusa",+ marker: "mid",+ tags: ["product", "pricing", "cart", "order", "payment", "fulfillment", "inventory", "promotion"],+ },+ {+ label: "Yours",+ sub: "src/",+ marker: "lo",+ tags: [+ { tag: "modules", dashed: true },+ { tag: "workflow hooks", dashed: true },+ { tag: "api routes", dashed: true },+ { tag: "subscribers", dashed: true },+ { tag: "blocks", dashed: true },+ ],+ },+ {+ label: "Links",+ sub: "defineLink",+ marker: "lo",+ tags: ["product ↔ seller", "offer ↔ variant", "order-group ↔ order"],+ },+]++const INFRA = [+ ["PostgreSQL", "one database"],+ ["Redis", "events · workflows · locks"],+ ["Providers", "payments · payouts · search"],+]++const X = 40+const W = 960++export default {+ name: "architecture-layers",+ width: 1040,+ height: 1090,+ alt: "Mercur's architecture: the admin and vendor panels, a storefront, and your services call the backend through @mercurjs/client. The backend exposes /admin, /vendor, and /store and runs marketplace modules from @mercurjs/core beside Medusa's commerce modules and your own code, over PostgreSQL, Redis, and providers.",+ draw(f) {+ const cw = (W - 3 * 24) / 4+ const cx = (i) => X + i * (cw + 24) + cw / 2+ const sw = W / 3+ const sx = (i) => X + i * sw + sw / 2++ const clientTop = 48+ const clientBottom = clientTop + 132+ CLIENTS.forEach(([title, a, b], i) => {+ f.panel({ x: X + i * (cw + 24), y: clientTop, w: cw, h: 132, name: title }, (p) => {+ p.header({ h: 60, marker: "hi", title, pad: 20 })+ p.label(20, 60 + 26, a, { size: 15, tone: "text" })+ p.label(20, 60 + 50, b, { size: 15, tone: "lo" })+ })+ })++ const bandTop = clientBottom + 40+ CLIENTS.forEach((_, i) => f.wire([[cx(i), clientBottom], [cx(i), bandTop]]))+ const band = f.panel({ x: X, y: bandTop, w: W, h: 64, name: "client" }, (p) => {+ const w = p.label(24, 32, "@mercurjs/client", { tone: "hi", weight: 500 })+ p.label(24 + w + 24, 32, "typed by mercurjs codegen", { size: 15, tone: "lo" })+ p.label(W - 24, 32, "@mercurjs/types", { size: 15, tone: "mid", anchor: "end" })+ })++ const backendTop = band.y + band.h + 44+ SURFACES.forEach((_, i) => f.wire([[sx(i), band.y + band.h], [sx(i), backendTop]]))++ const backend = f.panel({ x: X, y: backendTop, w: W, name: "backend" }, (p) => {+ SURFACES.forEach(([path, scope], i) => {+ if (i) p.line(i * sw, 0, i * sw, 72)+ p.label(i * sw + 24, 36, path, { tone: "hi", weight: 500 })+ p.label((i + 1) * sw - 24, 36, scope, { size: 15, tone: "lo", anchor: "end" })+ })+ p.line(0, 72, W, 72)++ let y = 72+ for (const d of DOMAINS) {+ const top = y + 14+ const lx = 24 + p.marker(24, top + 21, d.marker) + 12+ p.label(lx, top + 21, d.label, { size: 14, tone: "hi", caps: true })+ p.label(lx, top + 46, d.sub, { size: 15, tone: "lo" })+ const bottom = Math.max(p.tags(244, top, W - 244 - 24, d.tags), top + 62)+ y = bottom + 14+ p.line(0, y, W, y, { stroke: f.t.rule })+ }++ p.label(24, y + 28, "withMercur() · one Node process", { size: 15, tone: "lo" })+ p.label(W - 24, y + 28, "route → workflow → module", { size: 15, tone: "lo", anchor: "end" })+ return y + 56+ })++ const iw = (W - 2 * 24) / 3+ const backendBottom = backend.y + backend.h+ const infraTop = backendBottom + 56+ INFRA.forEach(([title, sub], i) => {+ const x = X + i * (iw + 24)+ f.wire([[x + iw / 2, backendBottom], [x + iw / 2, infraTop]])+ f.panel({ x, y: infraTop, w: iw, h: 112, name: title }, (p) => {+ p.header({ h: 60, marker: "lo", title, pad: 20 })+ p.label(20, 60 + 26, sub, { size: 15, tone: "mid" })+ })+ })++ f.tiles({+ seed: 4,+ density: 0.22,+ clear: [+ { x: X, y: clientBottom, w: W, h: bandTop - clientBottom },+ { x: X, y: band.y + band.h, w: W, h: backendTop - band.y - band.h },+ { x: X, y: backendBottom, w: W, h: infraTop - backendBottom },+ ],+ })+ },+}diff --git a/apps/docs/figures/extension-zones.mjs b/apps/docs/figures/extension-zones.mjsnew file mode 100644index 000000000..f5432fa2d--- /dev/null+++ b/apps/docs/figures/extension-zones.mjs@@ -0,0 +1,94 @@+export default {+ name: "extension-zones",+ width: 1040,+ height: 870,+ alt: "Stacked panels for Blocks, Panels, and Backend, with an Extensions table in front listing one file per zone: a workflow hook, an API route, a module, a custom field, a page, and a widget, each with its typed target.",+ draw(f) {+ f.tiles({ seed: 23 })+ f.cascade({ x: 40, y: 298, w: 826, h: 514, dx: -48 }, [+ (p) => {+ p.header({ marker: "amber", title: "Blocks", tabs: ["Installed", "Registry"], toggle: { on: false, label: "Overwrite" } })+ p.table({+ y: 76,+ columns: [+ { label: "Block", w: 300 },+ { label: "Files", w: 200 },+ { label: "Upstream", w: 262, align: "right" },+ ],+ rows: [+ ["wishlist", "9", { chip: "Synced", tone: "green" }],+ ["algolia", "6", { chip: "Diff", tone: "amber" }],+ ["vendor-chat", "21", { chip: "Synced", tone: "green" }],+ ["requests", "17", { chip: "Synced", tone: "green" }],+ ["vendor-notifications", "11", { chip: "Diff", tone: "amber" }],+ ["meilisearch", "6", { chip: "Synced", tone: "green" }],+ ],+ })+ },+ (p) => {+ p.header({+ marker: "green",+ title: "Panels",+ tabs: ["Pages", "Widgets", "Fields", "Navigation"],+ active: 1,+ toggle: { on: true, label: "Typed" },+ })+ p.table({+ y: 76,+ columns: [+ { label: "File", w: 380 },+ { label: "Zone", w: 382, align: "right" },+ ],+ rows: [+ ["payout-summary.tsx", "orders.detail.side.after"],+ ["order-sla.tsx", "orders.list.before"],+ ["offer-badges.tsx", "offers.list.after"],+ ["offer-docs.tsx", "offers.detail.main.after"],+ ["vip-note.tsx", "customers.detail.side"],+ ],+ })+ },+ (p) => {+ p.header({ marker: "hi", title: "Backend", tabs: ["Hooks", "Routes", "Modules"], note: "src/" })+ p.table({+ y: 76,+ columns: [+ { label: "Name", w: 300 },+ { label: "Workflow", w: 462, align: "right" },+ ],+ rows: [+ ["sellerApproved", "approveSellerWorkflow"],+ ["orderGroupCreated", "completeCartWithSplitOrdersWorkflow"],+ ["offersCreated", "createOffersWorkflow"],+ ["productChangeConfirmed", "confirmProductChangeWorkflow"],+ ["payoutCreated", "createPayoutWorkflow"],+ ],+ })+ },+ (p) => {+ p.header({+ marker: "violet",+ title: "Extensions",+ tabs: ["All", "Backend", "Panels"],+ toggle: { on: true, label: "Typecheck" },+ })+ p.table({+ y: 76,+ columns: [+ { label: "Path", w: 414 },+ { label: "Zone", w: 128 },+ { label: "Target", w: 220 },+ ],+ rows: [+ { accent: true, cells: ["src/workflows/hooks/seller-approved.ts", { tag: "hook" }, "sellerApproved"] },+ ["src/api/vendor/sellers/documents/route.ts", { tag: "route" }, { text: "/vendor/sellers/…", tone: "text" }],+ ["src/modules/subscription/index.ts", { tag: "module" }, { text: "↔ seller", tone: "text" }],+ ["medusa-config.ts", { tag: "field" }, { text: "Product.is_featured", tone: "text" }],+ ["src/routes/reports/page.tsx", { tag: "page" }, { text: "/reports", tone: "text" }],+ ["src/widgets/payout-summary.tsx", { tag: "widget" }, { text: "orders.detail.side", tone: "text" }],+ ],+ })+ },+ ])+ },+}diff --git a/apps/docs/figures/order-split.mjs b/apps/docs/figures/order-split.mjsnew file mode 100644index 000000000..4d3c2309e--- /dev/null+++ b/apps/docs/figures/order-split.mjs@@ -0,0 +1,78 @@+export default {+ name: "order-split",+ width: 1040,+ height: 610,+ alt: "A cart with items from two sellers becomes order group #G98, split into order #100 for ACME and order #99 for GLOBEX, each with its own status, commission, and payout.",+ draw(f) {+ f.tiles({ seed: 11 })+ f.cascade({ x: 40, y: 168, w: 900, h: 387 }, [+ (p) => {+ p.header({ marker: "amber", title: "Cart", tabs: ["Items", "Shipping", "Payment"], note: "cart_01JD8Q" })+ p.table({+ y: 76,+ columns: [+ { label: "Item", w: 300 },+ { label: "Seller", w: 200 },+ { label: "Qty", w: 120, align: "right" },+ { label: "Price", w: 216, align: "right" },+ ],+ rows: [+ ["Linen shirt", "ACME", "1", "€ 47.00"],+ ["Desk lamp", "GLOBEX", "1", "€ 40.00"],+ ["Shipping", "", "", "€ 0.00"],+ ],+ })+ },+ (p) => {+ p.header({+ marker: "violet",+ title: "Orders",+ tabs: ["All", "Groups", "Returns"],+ active: 1,+ toggle: { on: true, label: "Split by seller" },+ })+ p.table({+ y: 76,+ columns: [+ { label: "Order", w: 120 },+ { label: "Store", w: 150 },+ { label: "Status", w: 220 },+ { label: "Commission", w: 120, align: "right" },+ { label: "Payout", w: 110, align: "right" },+ { label: "Total", w: 116, align: "right" },+ ],+ rows: [+ {+ accent: true,+ cells: [{ caret: true, text: "#G98" }, "2 stores", "", "€ 8.70", "€ 78.30", "€ 87.00"],+ },+ [+ { indent: 32, text: "#100" },+ "ACME",+ { chip: "Not fulfilled", tone: "red" },+ { text: "€ 4.70", tone: "mid" },+ { text: "€ 42.30", tone: "mid" },+ "€ 47.00",+ ],+ [+ { indent: 32, text: "#99" },+ "GLOBEX",+ { chip: "Delivered", tone: "green" },+ { text: "€ 4.00", tone: "mid" },+ { text: "€ 36.00", tone: "mid" },+ "€ 40.00",+ ],+ [+ { caret: false, text: "#G97", tone: "mid" },+ { text: "1 store", tone: "mid" },+ "",+ { text: "€ 2.10", tone: "mid" },+ { text: "€ 18.90", tone: "mid" },+ { text: "€ 21.00", tone: "mid" },+ ],+ ],+ })+ },+ ])+ },+}diff --git a/apps/docs/images/figures/architecture-layers-dark.svg b/apps/docs/images/figures/architecture-layers-dark.svgnew file mode 100644index 000000000..e47adef98--- /dev/null+++ b/apps/docs/images/figures/architecture-layers-dark.svg@@ -0,0 +1,5 @@+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="1090" viewBox="0 0 1040 1090" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="Mercur's architecture: the admin and vendor panels, a storefront, and your services call the backend through @mercurjs/client. The backend exposes /admin, /vendor, and /store and runs marketplace modules from @mercurjs/core beside Medusa's commerce modules and your own code, over PostgreSQL, Redis, and providers.">+<title>Mercur's architecture: the admin and vendor panels, a storefront, and your services call the backend through @mercurjs/client. The backend exposes /admin, /vendor, and /store and runs marketplace modules from @mercurjs/core beside Medusa's commerce modules and your own code, over PostgreSQL, Redis, and providers.</title>+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="222" height="132"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="222" height="132"/></clipPath><clipPath id="c3"><rect x="0" y="0" width="222" height="132"/></clipPath><clipPath id="c4"><rect x="0" y="0" width="222" height="132"/></clipPath><clipPath id="c5"><rect x="0" y="0" width="960" height="64"/></clipPath><clipPath id="c6"><rect x="0" y="0" width="960" height="532"/></clipPath><clipPath id="c7"><rect x="0" y="0" width="304" height="112"/></clipPath><clipPath id="c8"><rect x="0" y="0" width="304" height="112"/></clipPath><clipPath id="c9"><rect x="0" y="0" width="304" height="112"/></clipPath></defs>+<rect x="88.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="264" y="-88" width="88" height="88" fill="#1d1926"/><rect x="264" y="-88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968" y="0" width="88" height="88" fill="url(#dt)"/><rect x="0" y="88" width="88" height="88" fill="#1d1926"/><rect x="0" y="88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="352" y="88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="88" width="88" height="88" fill="#1d1926"/><rect x="616" y="88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968" y="88" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="176.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-88" y="440" width="88" height="88" fill="url(#dt)"/><rect x="704.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="264" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="#1d1926"/><rect x="352" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0" y="616" width="88" height="88" fill="url(#dt)"/><rect x="88" y="616" width="88" height="88" fill="#1d1926"/><rect x="88" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="704" y="704" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="968" width="88" height="88" fill="#1d1926"/><rect x="440" y="968" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968" y="968" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="1056.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="1056.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="1056" width="88" height="88" fill="#1d1926"/><rect x="792" y="1056" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="352" y="1144" width="88" height="88" fill="#1d1926"/><rect x="352" y="1144" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="528.5" y="1144.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704.5" y="1144.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="40" y="48" width="222" height="132" fill="#15121d" filter="url(#sh)"/><rect x="40" y="48" width="222" height="132" fill="#15121d"/><g transform="translate(40 48)"><g clip-path="url(#c1)"><rect x="20" y="25" width="10" height="10" fill="#f4f4f5"/><text x="42" y="36.3" font-size="18" fill="#f4f4f5" font-weight="500">Admin</text><line x1="0" y1="60" x2="222" y2="60" stroke="#2b2636" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#d4d4d8">@mercurjs/admin</text><text x="20" y="115.3" font-size="15" fill="#71717a">dashboard-sdk</text></g></g><rect x="40.5" y="48.5" width="221" height="131" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="286" y="48" width="222" height="132" fill="#15121d" filter="url(#sh)"/><rect x="286" y="48" width="222" height="132" fill="#15121d"/><g transform="translate(286 48)"><g clip-path="url(#c2)"><rect x="20" y="25" width="10" height="10" fill="#f4f4f5"/><text x="42" y="36.3" font-size="18" fill="#f4f4f5" font-weight="500">Vendor</text><line x1="0" y1="60" x2="222" y2="60" stroke="#2b2636" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#d4d4d8">@mercurjs/vendor</text><text x="20" y="115.3" font-size="15" fill="#71717a">dashboard-sdk</text></g></g><rect x="286.5" y="48.5" width="221" height="131" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="532" y="48" width="222" height="132" fill="#15121d" filter="url(#sh)"/><rect x="532" y="48" width="222" height="132" fill="#15121d"/><g transform="translate(532 48)"><g clip-path="url(#c3)"><rect x="20" y="25" width="10" height="10" fill="#f4f4f5"/><text x="42" y="36.3" font-size="18" fill="#f4f4f5" font-weight="500">Storefront</text><line x1="0" y1="60" x2="222" y2="60" stroke="#2b2636" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#d4d4d8">Next.js or any</text><text x="20" y="115.3" font-size="15" fill="#71717a">framework</text></g></g><rect x="532.5" y="48.5" width="221" height="131" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="778" y="48" width="222" height="132" fill="#15121d" filter="url(#sh)"/><rect x="778" y="48" width="222" height="132" fill="#15121d"/><g transform="translate(778 48)"><g clip-path="url(#c4)"><rect x="20" y="25" width="10" height="10" fill="#f4f4f5"/><text x="42" y="36.3" font-size="18" fill="#f4f4f5" font-weight="500">Services</text><line x1="0" y1="60" x2="222" y2="60" stroke="#2b2636" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#d4d4d8">ERP · PIM</text><text x="20" y="115.3" font-size="15" fill="#71717a">AI agents</text></g></g><rect x="778.5" y="48.5" width="221" height="131" fill="none" stroke="#2b2636" stroke-width="1"/><path d="M151 180 L151 220" fill="none" stroke="#3d3749" stroke-width="1"/><rect x="148" y="217" width="6" height="6" fill="#3d3749"/><path d="M397 180 L397 220" fill="none" stroke="#3d3749" stroke-width="1"/><rect x="394" y="217" width="6" height="6" fill="#3d3749"/><path d="M643 180 L643 220" fill="none" stroke="#3d3749" stroke-width="1"/><rect x="640" y="217" width="6" height="6" fill="#3d3749"/><path d="M889 180 L889 220" fill="none" stroke="#3d3749" stroke-width="1"/><rect x="886" y="217" width="6" height="6" fill="#3d3749"/><rect x="40" y="220" width="960" height="64" fill="#15121d" filter="url(#sh)"/><rect x="40" y="220" width="960" height="64" fill="#15121d"/><g transform="translate(40 220)"><g clip-path="url(#c5)"><text x="24" y="37.6" font-size="16" fill="#f4f4f5" font-weight="500">@mercurjs/client</text><text x="201.6" y="37.3" font-size="15" fill="#71717a">typed by mercurjs codegen</text><text x="936" y="37.3" font-size="15" fill="#a1a1aa" text-anchor="end">@mercurjs/types</text></g></g><rect x="40.5" y="220.5" width="959" height="63" fill="none" stroke="#2b2636" stroke-width="1"/><path d="M200 284 L200 328" fill="none" stroke="#3d3749" stroke-width="1"/><rect x="197" y="325" width="6" height="6" fill="#3d3749"/><path d="M520 284 L520 328" fill="none" stroke="#3d3749" stroke-width="1"/><rect x="517" y="325" width="6" height="6" fill="#3d3749"/><path d="M840 284 L840 328" fill="none" stroke="#3d3749" stroke-width="1"/><rect x="837" y="325" width="6" height="6" fill="#3d3749"/><rect x="40" y="328" width="960" height="532" fill="#15121d" filter="url(#sh)"/><rect x="40" y="328" width="960" height="532" fill="#15121d"/><g transform="translate(40 328)"><g clip-path="url(#c6)"><text x="24" y="41.6" font-size="16" fill="#f4f4f5" font-weight="500">/admin/*</text><text x="296" y="41.3" font-size="15" fill="#71717a" text-anchor="end">role-gated</text><line x1="320" y1="0" x2="320" y2="72" stroke="#2b2636" stroke-width="1"/><text x="344" y="41.6" font-size="16" fill="#f4f4f5" font-weight="500">/vendor/*</text><text x="616" y="41.3" font-size="15" fill="#71717a" text-anchor="end">seller-scoped</text><line x1="640" y1="0" x2="640" y2="72" stroke="#2b2636" stroke-width="1"/><text x="664" y="41.6" font-size="16" fill="#f4f4f5" font-weight="500">/store/*</text><text x="936" y="41.3" font-size="15" fill="#71717a" text-anchor="end">public</text><line x1="0" y1="72" x2="960" y2="72" stroke="#2b2636" stroke-width="1"/><rect x="24" y="102" width="10" height="10" fill="#a78bfa"/><text x="46" y="111.9" font-size="14" fill="#f4f4f5" letter-spacing="1.2">MARKETPLACE</text><text x="46" y="137.3" font-size="15" fill="#71717a">@mercurjs/core</text><rect x="244" y="92" width="78" height="30" fill="#1f1b29"/><text x="256" y="112.3" font-size="15" fill="#a1a1aa">seller</text><rect x="332" y="92" width="69" height="30" fill="#1f1b29"/><text x="344" y="112.3" font-size="15" fill="#a1a1aa">offer</text><rect x="411" y="92" width="114" height="30" fill="#1f1b29"/><text x="423" y="112.3" font-size="15" fill="#a1a1aa">commission</text><rect x="535" y="92" width="78" height="30" fill="#1f1b29"/><text x="547" y="112.3" font-size="15" fill="#a1a1aa">payout</text><rect x="623" y="92" width="132" height="30" fill="#1f1b29"/><text x="635" y="112.3" font-size="15" fill="#a1a1aa">product-edit</text><rect x="244" y="134" width="177" height="30" fill="#1f1b29"/><text x="256" y="154.3" font-size="15" fill="#a1a1aa">product-attribute</text><rect x="431" y="134" width="78" height="30" fill="#1f1b29"/><text x="443" y="154.3" font-size="15" fill="#a1a1aa">review</text><rect x="519" y="134" width="141" height="30" fill="#1f1b29"/><text x="531" y="154.3" font-size="15" fill="#a1a1aa">custom-fields</text><line x1="0" y1="184" x2="960" y2="184" stroke="#221e2b" stroke-width="1"/><rect x="24" y="214" width="10" height="10" fill="#a1a1aa"/><text x="46" y="223.9" font-size="14" fill="#f4f4f5" letter-spacing="1.2">COMMERCE</text><text x="46" y="249.3" font-size="15" fill="#71717a">@medusajs/medusa</text><rect x="244" y="204" width="87" height="30" fill="#1f1b29"/><text x="256" y="224.3" font-size="15" fill="#a1a1aa">product</text><rect x="341" y="204" width="87" height="30" fill="#1f1b29"/><text x="353" y="224.3" font-size="15" fill="#a1a1aa">pricing</text><rect x="438" y="204" width="60" height="30" fill="#1f1b29"/><text x="450" y="224.3" font-size="15" fill="#a1a1aa">cart</text><rect x="508" y="204" width="69" height="30" fill="#1f1b29"/><text x="520" y="224.3" font-size="15" fill="#a1a1aa">order</text><rect x="587" y="204" width="87" height="30" fill="#1f1b29"/><text x="599" y="224.3" font-size="15" fill="#a1a1aa">payment</text><rect x="684" y="204" width="123" height="30" fill="#1f1b29"/><text x="696" y="224.3" font-size="15" fill="#a1a1aa">fulfillment</text><rect x="817" y="204" width="105" height="30" fill="#1f1b29"/><text x="829" y="224.3" font-size="15" fill="#a1a1aa">inventory</text><rect x="244" y="246" width="105" height="30" fill="#1f1b29"/><text x="256" y="266.3" font-size="15" fill="#a1a1aa">promotion</text><line x1="0" y1="296" x2="960" y2="296" stroke="#221e2b" stroke-width="1"/><rect x="24" y="326" width="10" height="10" fill="#71717a"/><text x="46" y="335.9" font-size="14" fill="#f4f4f5" letter-spacing="1.2">YOURS</text><text x="46" y="361.3" font-size="15" fill="#71717a">src/</text><rect x="244.5" y="316.5" width="86" height="29" fill="none" stroke="#3d3749" stroke-width="1" stroke-dasharray="3 3"/><text x="256" y="336.3" font-size="15" fill="#a1a1aa">modules</text><rect x="341.5" y="316.5" width="149" height="29" fill="none" stroke="#3d3749" stroke-width="1" stroke-dasharray="3 3"/><text x="353" y="336.3" font-size="15" fill="#a1a1aa">workflow hooks</text><rect x="501.5" y="316.5" width="113" height="29" fill="none" stroke="#3d3749" stroke-width="1" stroke-dasharray="3 3"/><text x="513" y="336.3" font-size="15" fill="#a1a1aa">api routes</text><rect x="625.5" y="316.5" width="122" height="29" fill="none" stroke="#3d3749" stroke-width="1" stroke-dasharray="3 3"/><text x="637" y="336.3" font-size="15" fill="#a1a1aa">subscribers</text><rect x="758.5" y="316.5" width="77" height="29" fill="none" stroke="#3d3749" stroke-width="1" stroke-dasharray="3 3"/><text x="770" y="336.3" font-size="15" fill="#a1a1aa">blocks</text><line x1="0" y1="386" x2="960" y2="386" stroke="#221e2b" stroke-width="1"/><rect x="24" y="416" width="10" height="10" fill="#71717a"/><text x="46" y="425.9" font-size="14" fill="#f4f4f5" letter-spacing="1.2">LINKS</text><text x="46" y="451.3" font-size="15" fill="#71717a">defineLink</text><rect x="244" y="406" width="168" height="30" fill="#1f1b29"/><text x="256" y="426.3" font-size="15" fill="#a1a1aa">product ↔ seller</text><rect x="422" y="406" width="159" height="30" fill="#1f1b29"/><text x="434" y="426.3" font-size="15" fill="#a1a1aa">offer ↔ variant</text><rect x="591" y="406" width="195" height="30" fill="#1f1b29"/><text x="603" y="426.3" font-size="15" fill="#a1a1aa">order-group ↔ order</text><line x1="0" y1="476" x2="960" y2="476" stroke="#221e2b" stroke-width="1"/><text x="24" y="509.3" font-size="15" fill="#71717a">withMercur() · one Node process</text><text x="936" y="509.3" font-size="15" fill="#71717a" text-anchor="end">route → workflow → module</text></g></g><rect x="40.5" y="328.5" width="959" height="531" fill="none" stroke="#2b2636" stroke-width="1"/><path d="M192 860 L192 916" fill="none" stroke="#3d3749" stroke-width="1"/><rect x="189" y="913" width="6" height="6" fill="#3d3749"/><rect x="40" y="916" width="304" height="112" fill="#15121d" filter="url(#sh)"/><rect x="40" y="916" width="304" height="112" fill="#15121d"/><g transform="translate(40 916)"><g clip-path="url(#c7)"><rect x="20" y="25" width="10" height="10" fill="#71717a"/><text x="42" y="36.3" font-size="18" fill="#f4f4f5" font-weight="500">PostgreSQL</text><line x1="0" y1="60" x2="304" y2="60" stroke="#2b2636" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#a1a1aa">one database</text></g></g><rect x="40.5" y="916.5" width="303" height="111" fill="none" stroke="#2b2636" stroke-width="1"/><path d="M520 860 L520 916" fill="none" stroke="#3d3749" stroke-width="1"/><rect x="517" y="913" width="6" height="6" fill="#3d3749"/><rect x="368" y="916" width="304" height="112" fill="#15121d" filter="url(#sh)"/><rect x="368" y="916" width="304" height="112" fill="#15121d"/><g transform="translate(368 916)"><g clip-path="url(#c8)"><rect x="20" y="25" width="10" height="10" fill="#71717a"/><text x="42" y="36.3" font-size="18" fill="#f4f4f5" font-weight="500">Redis</text><line x1="0" y1="60" x2="304" y2="60" stroke="#2b2636" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#a1a1aa">events · workflows · locks</text></g></g><rect x="368.5" y="916.5" width="303" height="111" fill="none" stroke="#2b2636" stroke-width="1"/><path d="M848 860 L848 916" fill="none" stroke="#3d3749" stroke-width="1"/><rect x="845" y="913" width="6" height="6" fill="#3d3749"/><rect x="696" y="916" width="304" height="112" fill="#15121d" filter="url(#sh)"/><rect x="696" y="916" width="304" height="112" fill="#15121d"/><g transform="translate(696 916)"><g clip-path="url(#c9)"><rect x="20" y="25" width="10" height="10" fill="#71717a"/><text x="42" y="36.3" font-size="18" fill="#f4f4f5" font-weight="500">Providers</text><line x1="0" y1="60" x2="304" y2="60" stroke="#2b2636" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#a1a1aa">payments · payouts · search</text></g></g><rect x="696.5" y="916.5" width="303" height="111" fill="none" stroke="#2b2636" stroke-width="1"/>+</svg>\ No newline at end of filediff --git a/apps/docs/images/figures/architecture-layers-light.svg b/apps/docs/images/figures/architecture-layers-light.svgnew file mode 100644index 000000000..53aab8941--- /dev/null+++ b/apps/docs/images/figures/architecture-layers-light.svg@@ -0,0 +1,5 @@+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="1090" viewBox="0 0 1040 1090" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="Mercur's architecture: the admin and vendor panels, a storefront, and your services call the backend through @mercurjs/client. The backend exposes /admin, /vendor, and /store and runs marketplace modules from @mercurjs/core beside Medusa's commerce modules and your own code, over PostgreSQL, Redis, and providers.">+<title>Mercur's architecture: the admin and vendor panels, a storefront, and your services call the backend through @mercurjs/client. The backend exposes /admin, /vendor, and /store and runs marketplace modules from @mercurjs/core beside Medusa's commerce modules and your own code, over PostgreSQL, Redis, and providers.</title>+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="222" height="132"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="222" height="132"/></clipPath><clipPath id="c3"><rect x="0" y="0" width="222" height="132"/></clipPath><clipPath id="c4"><rect x="0" y="0" width="222" height="132"/></clipPath><clipPath id="c5"><rect x="0" y="0" width="960" height="64"/></clipPath><clipPath id="c6"><rect x="0" y="0" width="960" height="532"/></clipPath><clipPath id="c7"><rect x="0" y="0" width="304" height="112"/></clipPath><clipPath id="c8"><rect x="0" y="0" width="304" height="112"/></clipPath><clipPath id="c9"><rect x="0" y="0" width="304" height="112"/></clipPath></defs>+<rect x="88.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="264" y="-88" width="88" height="88" fill="#e4e4e7"/><rect x="264" y="-88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968" y="0" width="88" height="88" fill="url(#dt)"/><rect x="0" y="88" width="88" height="88" fill="#e4e4e7"/><rect x="0" y="88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="352" y="88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="88" width="88" height="88" fill="#e4e4e7"/><rect x="616" y="88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968" y="88" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="176.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-88" y="440" width="88" height="88" fill="url(#dt)"/><rect x="704.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="264" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="352" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0" y="616" width="88" height="88" fill="url(#dt)"/><rect x="88" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="88" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="704" y="704" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="968" width="88" height="88" fill="#e4e4e7"/><rect x="440" y="968" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968" y="968" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="1056.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="1056.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="1056" width="88" height="88" fill="#e4e4e7"/><rect x="792" y="1056" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="352" y="1144" width="88" height="88" fill="#e4e4e7"/><rect x="352" y="1144" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="528.5" y="1144.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704.5" y="1144.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="40" y="48" width="222" height="132" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="48" width="222" height="132" fill="#ffffff"/><g transform="translate(40 48)"><g clip-path="url(#c1)"><rect x="20" y="25" width="10" height="10" fill="#18181b"/><text x="42" y="36.3" font-size="18" fill="#18181b" font-weight="500">Admin</text><line x1="0" y1="60" x2="222" y2="60" stroke="#e4e4e7" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#3f3f46">@mercurjs/admin</text><text x="20" y="115.3" font-size="15" fill="#a1a1aa">dashboard-sdk</text></g></g><rect x="40.5" y="48.5" width="221" height="131" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="286" y="48" width="222" height="132" fill="#ffffff" filter="url(#sh)"/><rect x="286" y="48" width="222" height="132" fill="#ffffff"/><g transform="translate(286 48)"><g clip-path="url(#c2)"><rect x="20" y="25" width="10" height="10" fill="#18181b"/><text x="42" y="36.3" font-size="18" fill="#18181b" font-weight="500">Vendor</text><line x1="0" y1="60" x2="222" y2="60" stroke="#e4e4e7" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#3f3f46">@mercurjs/vendor</text><text x="20" y="115.3" font-size="15" fill="#a1a1aa">dashboard-sdk</text></g></g><rect x="286.5" y="48.5" width="221" height="131" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="532" y="48" width="222" height="132" fill="#ffffff" filter="url(#sh)"/><rect x="532" y="48" width="222" height="132" fill="#ffffff"/><g transform="translate(532 48)"><g clip-path="url(#c3)"><rect x="20" y="25" width="10" height="10" fill="#18181b"/><text x="42" y="36.3" font-size="18" fill="#18181b" font-weight="500">Storefront</text><line x1="0" y1="60" x2="222" y2="60" stroke="#e4e4e7" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#3f3f46">Next.js or any</text><text x="20" y="115.3" font-size="15" fill="#a1a1aa">framework</text></g></g><rect x="532.5" y="48.5" width="221" height="131" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="778" y="48" width="222" height="132" fill="#ffffff" filter="url(#sh)"/><rect x="778" y="48" width="222" height="132" fill="#ffffff"/><g transform="translate(778 48)"><g clip-path="url(#c4)"><rect x="20" y="25" width="10" height="10" fill="#18181b"/><text x="42" y="36.3" font-size="18" fill="#18181b" font-weight="500">Services</text><line x1="0" y1="60" x2="222" y2="60" stroke="#e4e4e7" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#3f3f46">ERP · PIM</text><text x="20" y="115.3" font-size="15" fill="#a1a1aa">AI agents</text></g></g><rect x="778.5" y="48.5" width="221" height="131" fill="none" stroke="#e4e4e7" stroke-width="1"/><path d="M151 180 L151 220" fill="none" stroke="#c4c4cc" stroke-width="1"/><rect x="148" y="217" width="6" height="6" fill="#c4c4cc"/><path d="M397 180 L397 220" fill="none" stroke="#c4c4cc" stroke-width="1"/><rect x="394" y="217" width="6" height="6" fill="#c4c4cc"/><path d="M643 180 L643 220" fill="none" stroke="#c4c4cc" stroke-width="1"/><rect x="640" y="217" width="6" height="6" fill="#c4c4cc"/><path d="M889 180 L889 220" fill="none" stroke="#c4c4cc" stroke-width="1"/><rect x="886" y="217" width="6" height="6" fill="#c4c4cc"/><rect x="40" y="220" width="960" height="64" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="220" width="960" height="64" fill="#ffffff"/><g transform="translate(40 220)"><g clip-path="url(#c5)"><text x="24" y="37.6" font-size="16" fill="#18181b" font-weight="500">@mercurjs/client</text><text x="201.6" y="37.3" font-size="15" fill="#a1a1aa">typed by mercurjs codegen</text><text x="936" y="37.3" font-size="15" fill="#71717a" text-anchor="end">@mercurjs/types</text></g></g><rect x="40.5" y="220.5" width="959" height="63" fill="none" stroke="#e4e4e7" stroke-width="1"/><path d="M200 284 L200 328" fill="none" stroke="#c4c4cc" stroke-width="1"/><rect x="197" y="325" width="6" height="6" fill="#c4c4cc"/><path d="M520 284 L520 328" fill="none" stroke="#c4c4cc" stroke-width="1"/><rect x="517" y="325" width="6" height="6" fill="#c4c4cc"/><path d="M840 284 L840 328" fill="none" stroke="#c4c4cc" stroke-width="1"/><rect x="837" y="325" width="6" height="6" fill="#c4c4cc"/><rect x="40" y="328" width="960" height="532" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="328" width="960" height="532" fill="#ffffff"/><g transform="translate(40 328)"><g clip-path="url(#c6)"><text x="24" y="41.6" font-size="16" fill="#18181b" font-weight="500">/admin/*</text><text x="296" y="41.3" font-size="15" fill="#a1a1aa" text-anchor="end">role-gated</text><line x1="320" y1="0" x2="320" y2="72" stroke="#e4e4e7" stroke-width="1"/><text x="344" y="41.6" font-size="16" fill="#18181b" font-weight="500">/vendor/*</text><text x="616" y="41.3" font-size="15" fill="#a1a1aa" text-anchor="end">seller-scoped</text><line x1="640" y1="0" x2="640" y2="72" stroke="#e4e4e7" stroke-width="1"/><text x="664" y="41.6" font-size="16" fill="#18181b" font-weight="500">/store/*</text><text x="936" y="41.3" font-size="15" fill="#a1a1aa" text-anchor="end">public</text><line x1="0" y1="72" x2="960" y2="72" stroke="#e4e4e7" stroke-width="1"/><rect x="24" y="102" width="10" height="10" fill="#7c3aed"/><text x="46" y="111.9" font-size="14" fill="#18181b" letter-spacing="1.2">MARKETPLACE</text><text x="46" y="137.3" font-size="15" fill="#a1a1aa">@mercurjs/core</text><rect x="244" y="92" width="78" height="30" fill="#f4f4f5"/><text x="256" y="112.3" font-size="15" fill="#71717a">seller</text><rect x="332" y="92" width="69" height="30" fill="#f4f4f5"/><text x="344" y="112.3" font-size="15" fill="#71717a">offer</text><rect x="411" y="92" width="114" height="30" fill="#f4f4f5"/><text x="423" y="112.3" font-size="15" fill="#71717a">commission</text><rect x="535" y="92" width="78" height="30" fill="#f4f4f5"/><text x="547" y="112.3" font-size="15" fill="#71717a">payout</text><rect x="623" y="92" width="132" height="30" fill="#f4f4f5"/><text x="635" y="112.3" font-size="15" fill="#71717a">product-edit</text><rect x="244" y="134" width="177" height="30" fill="#f4f4f5"/><text x="256" y="154.3" font-size="15" fill="#71717a">product-attribute</text><rect x="431" y="134" width="78" height="30" fill="#f4f4f5"/><text x="443" y="154.3" font-size="15" fill="#71717a">review</text><rect x="519" y="134" width="141" height="30" fill="#f4f4f5"/><text x="531" y="154.3" font-size="15" fill="#71717a">custom-fields</text><line x1="0" y1="184" x2="960" y2="184" stroke="#ededf0" stroke-width="1"/><rect x="24" y="214" width="10" height="10" fill="#71717a"/><text x="46" y="223.9" font-size="14" fill="#18181b" letter-spacing="1.2">COMMERCE</text><text x="46" y="249.3" font-size="15" fill="#a1a1aa">@medusajs/medusa</text><rect x="244" y="204" width="87" height="30" fill="#f4f4f5"/><text x="256" y="224.3" font-size="15" fill="#71717a">product</text><rect x="341" y="204" width="87" height="30" fill="#f4f4f5"/><text x="353" y="224.3" font-size="15" fill="#71717a">pricing</text><rect x="438" y="204" width="60" height="30" fill="#f4f4f5"/><text x="450" y="224.3" font-size="15" fill="#71717a">cart</text><rect x="508" y="204" width="69" height="30" fill="#f4f4f5"/><text x="520" y="224.3" font-size="15" fill="#71717a">order</text><rect x="587" y="204" width="87" height="30" fill="#f4f4f5"/><text x="599" y="224.3" font-size="15" fill="#71717a">payment</text><rect x="684" y="204" width="123" height="30" fill="#f4f4f5"/><text x="696" y="224.3" font-size="15" fill="#71717a">fulfillment</text><rect x="817" y="204" width="105" height="30" fill="#f4f4f5"/><text x="829" y="224.3" font-size="15" fill="#71717a">inventory</text><rect x="244" y="246" width="105" height="30" fill="#f4f4f5"/><text x="256" y="266.3" font-size="15" fill="#71717a">promotion</text><line x1="0" y1="296" x2="960" y2="296" stroke="#ededf0" stroke-width="1"/><rect x="24" y="326" width="10" height="10" fill="#a1a1aa"/><text x="46" y="335.9" font-size="14" fill="#18181b" letter-spacing="1.2">YOURS</text><text x="46" y="361.3" font-size="15" fill="#a1a1aa">src/</text><rect x="244.5" y="316.5" width="86" height="29" fill="none" stroke="#c4c4cc" stroke-width="1" stroke-dasharray="3 3"/><text x="256" y="336.3" font-size="15" fill="#71717a">modules</text><rect x="341.5" y="316.5" width="149" height="29" fill="none" stroke="#c4c4cc" stroke-width="1" stroke-dasharray="3 3"/><text x="353" y="336.3" font-size="15" fill="#71717a">workflow hooks</text><rect x="501.5" y="316.5" width="113" height="29" fill="none" stroke="#c4c4cc" stroke-width="1" stroke-dasharray="3 3"/><text x="513" y="336.3" font-size="15" fill="#71717a">api routes</text><rect x="625.5" y="316.5" width="122" height="29" fill="none" stroke="#c4c4cc" stroke-width="1" stroke-dasharray="3 3"/><text x="637" y="336.3" font-size="15" fill="#71717a">subscribers</text><rect x="758.5" y="316.5" width="77" height="29" fill="none" stroke="#c4c4cc" stroke-width="1" stroke-dasharray="3 3"/><text x="770" y="336.3" font-size="15" fill="#71717a">blocks</text><line x1="0" y1="386" x2="960" y2="386" stroke="#ededf0" stroke-width="1"/><rect x="24" y="416" width="10" height="10" fill="#a1a1aa"/><text x="46" y="425.9" font-size="14" fill="#18181b" letter-spacing="1.2">LINKS</text><text x="46" y="451.3" font-size="15" fill="#a1a1aa">defineLink</text><rect x="244" y="406" width="168" height="30" fill="#f4f4f5"/><text x="256" y="426.3" font-size="15" fill="#71717a">product ↔ seller</text><rect x="422" y="406" width="159" height="30" fill="#f4f4f5"/><text x="434" y="426.3" font-size="15" fill="#71717a">offer ↔ variant</text><rect x="591" y="406" width="195" height="30" fill="#f4f4f5"/><text x="603" y="426.3" font-size="15" fill="#71717a">order-group ↔ order</text><line x1="0" y1="476" x2="960" y2="476" stroke="#ededf0" stroke-width="1"/><text x="24" y="509.3" font-size="15" fill="#a1a1aa">withMercur() · one Node process</text><text x="936" y="509.3" font-size="15" fill="#a1a1aa" text-anchor="end">route → workflow → module</text></g></g><rect x="40.5" y="328.5" width="959" height="531" fill="none" stroke="#e4e4e7" stroke-width="1"/><path d="M192 860 L192 916" fill="none" stroke="#c4c4cc" stroke-width="1"/><rect x="189" y="913" width="6" height="6" fill="#c4c4cc"/><rect x="40" y="916" width="304" height="112" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="916" width="304" height="112" fill="#ffffff"/><g transform="translate(40 916)"><g clip-path="url(#c7)"><rect x="20" y="25" width="10" height="10" fill="#a1a1aa"/><text x="42" y="36.3" font-size="18" fill="#18181b" font-weight="500">PostgreSQL</text><line x1="0" y1="60" x2="304" y2="60" stroke="#e4e4e7" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#71717a">one database</text></g></g><rect x="40.5" y="916.5" width="303" height="111" fill="none" stroke="#e4e4e7" stroke-width="1"/><path d="M520 860 L520 916" fill="none" stroke="#c4c4cc" stroke-width="1"/><rect x="517" y="913" width="6" height="6" fill="#c4c4cc"/><rect x="368" y="916" width="304" height="112" fill="#ffffff" filter="url(#sh)"/><rect x="368" y="916" width="304" height="112" fill="#ffffff"/><g transform="translate(368 916)"><g clip-path="url(#c8)"><rect x="20" y="25" width="10" height="10" fill="#a1a1aa"/><text x="42" y="36.3" font-size="18" fill="#18181b" font-weight="500">Redis</text><line x1="0" y1="60" x2="304" y2="60" stroke="#e4e4e7" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#71717a">events · workflows · locks</text></g></g><rect x="368.5" y="916.5" width="303" height="111" fill="none" stroke="#e4e4e7" stroke-width="1"/><path d="M848 860 L848 916" fill="none" stroke="#c4c4cc" stroke-width="1"/><rect x="845" y="913" width="6" height="6" fill="#c4c4cc"/><rect x="696" y="916" width="304" height="112" fill="#ffffff" filter="url(#sh)"/><rect x="696" y="916" width="304" height="112" fill="#ffffff"/><g transform="translate(696 916)"><g clip-path="url(#c9)"><rect x="20" y="25" width="10" height="10" fill="#a1a1aa"/><text x="42" y="36.3" font-size="18" fill="#18181b" font-weight="500">Providers</text><line x1="0" y1="60" x2="304" y2="60" stroke="#e4e4e7" stroke-width="1"/><text x="20" y="91.3" font-size="15" fill="#71717a">payments · payouts · search</text></g></g><rect x="696.5" y="916.5" width="303" height="111" fill="none" stroke="#e4e4e7" stroke-width="1"/>+</svg>\ No newline at end of filediff --git a/apps/docs/images/figures/extension-zones-dark.svg b/apps/docs/images/figures/extension-zones-dark.svgnew file mode 100644index 000000000..a6f8049a8--- /dev/null+++ b/apps/docs/images/figures/extension-zones-dark.svg@@ -0,0 +1,5 @@+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="870" viewBox="0 0 1040 870" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="Stacked panels for Blocks, Panels, and Backend, with an Extensions table in front listing one file per zone: a workflow hook, an API route, a module, a custom field, a page, and a widget, each with its typed target.">+<title>Stacked panels for Blocks, Panels, and Backend, with an Extensions table in front listing one file per zone: a workflow hook, an API route, a module, a custom field, a page, and a widget, each with its typed target.</title>+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="826" height="514"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="826" height="514"/></clipPath><clipPath id="c3"><rect x="0" y="0" width="826" height="514"/></clipPath><clipPath id="c4"><rect x="0" y="0" width="826" height="514"/></clipPath></defs>+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="528.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="0" y="0" width="88" height="88" fill="#1d1926"/><rect x="0" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="88" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="176" width="88" height="88" fill="url(#dt)"/><rect x="440" y="176" width="88" height="88" fill="url(#dt)"/><rect x="704.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="264" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="352" width="88" height="88" fill="#1d1926"/><rect x="-88" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="528" y="352" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="440" width="88" height="88" fill="url(#dt)"/><rect x="0" y="440" width="88" height="88" fill="#1d1926"/><rect x="0" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="176.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616" y="440" width="88" height="88" fill="#1d1926"/><rect x="616" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="1056.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="528" width="88" height="88" fill="#1d1926"/><rect x="792" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968" y="528" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="616" width="88" height="88" fill="#1d1926"/><rect x="352" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="792" y="616" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="704" width="88" height="88" fill="url(#dt)"/><rect x="0" y="704" width="88" height="88" fill="url(#dt)"/><rect x="704.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="792.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="792" width="88" height="88" fill="url(#dt)"/><rect x="176" y="792" width="88" height="88" fill="#1d1926"/><rect x="176" y="792" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="264" y="792" width="88" height="88" fill="#1d1926"/><rect x="264" y="792" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="440.5" y="792.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704.5" y="792.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="792.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="792" width="88" height="88" fill="url(#dt)"/><rect x="176" y="880" width="88" height="88" fill="#1d1926"/><rect x="176" y="880" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="264" y="880" width="88" height="88" fill="url(#dt)"/><rect x="352" y="880" width="88" height="88" fill="#1d1926"/><rect x="352" y="880" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="440" y="880" width="88" height="88" fill="#1d1926"/><rect x="440" y="880" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="528.5" y="880.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616" y="880" width="88" height="88" fill="#1d1926"/><rect x="616" y="880" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="704" y="880" width="88" height="88" fill="url(#dt)"/><rect x="968" y="880" width="88" height="88" fill="#1d1926"/><rect x="968" y="880" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="184" y="40" width="826" height="514" fill="#15121d" filter="url(#sh)"/><rect x="184" y="40" width="826" height="514" fill="#15121d"/><g transform="translate(184 40)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#f2a14b"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Blocks</text><line x1="134.8" y1="20" x2="134.8" y2="56" stroke="#2b2636" stroke-width="1"/><text x="166.8" y="44" font-size="17" fill="#f4f4f5">Installed</text><rect x="148.8" y="73" width="127.8" height="3" fill="#f4f4f5"/><text x="298.6" y="44" font-size="17" fill="#a1a1aa">Registry</text><text x="721" y="43.3" font-size="15" fill="#d4d4d8">Overwrite</text><rect x="661" y="27" width="46" height="22" fill="#3f3a4b"/><rect x="664" y="30" width="19" height="16" fill="#15121d"/><line x1="0" y1="76" x2="826" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">BLOCK</text><text x="332" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">FILES</text><text x="794" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">UPSTREAM</text><line x1="0" y1="130" x2="826" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">wishlist</text><text x="332" y="167.6" font-size="16" fill="#f4f4f5">9</text><rect x="692.4" y="146" width="101.6" height="32" fill="#1f1b29"/><rect x="704.4" y="157" width="10" height="10" fill="#6fbf68"/><text x="726.4" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">SYNCED</text><line x1="0" y1="194" x2="826" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">algolia</text><text x="332" y="231.6" font-size="16" fill="#f4f4f5">6</text><rect x="711.6" y="210" width="82.4" height="32" fill="#1f1b29"/><rect x="723.6" y="221" width="10" height="10" fill="#f2a14b"/><text x="745.6" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">DIFF</text><line x1="0" y1="258" x2="826" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">vendor-chat</text><text x="332" y="295.6" font-size="16" fill="#f4f4f5">21</text><rect x="692.4" y="274" width="101.6" height="32" fill="#1f1b29"/><rect x="704.4" y="285" width="10" height="10" fill="#6fbf68"/><text x="726.4" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">SYNCED</text><line x1="0" y1="322" x2="826" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#f4f4f5">requests</text><text x="332" y="359.6" font-size="16" fill="#f4f4f5">17</text><rect x="692.4" y="338" width="101.6" height="32" fill="#1f1b29"/><rect x="704.4" y="349" width="10" height="10" fill="#6fbf68"/><text x="726.4" y="358.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">SYNCED</text><line x1="0" y1="386" x2="826" y2="386" stroke="#221e2b" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#f4f4f5">vendor-notifications</text><text x="332" y="423.6" font-size="16" fill="#f4f4f5">11</text><rect x="711.6" y="402" width="82.4" height="32" fill="#1f1b29"/><rect x="723.6" y="413" width="10" height="10" fill="#f2a14b"/><text x="745.6" y="422.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">DIFF</text><line x1="0" y1="450" x2="826" y2="450" stroke="#221e2b" stroke-width="1"/><text x="32" y="487.6" font-size="16" fill="#f4f4f5">meilisearch</text><text x="332" y="487.6" font-size="16" fill="#f4f4f5">6</text><rect x="692.4" y="466" width="101.6" height="32" fill="#1f1b29"/><rect x="704.4" y="477" width="10" height="10" fill="#6fbf68"/><text x="726.4" y="486.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">SYNCED</text><line x1="0" y1="514" x2="826" y2="514" stroke="#221e2b" stroke-width="1"/></g></g><rect x="184.5" y="40.5" width="825" height="513" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="136" y="126" width="826" height="514" fill="#15121d" filter="url(#sh)"/><rect x="136" y="126" width="826" height="514" fill="#15121d"/><g transform="translate(136 126)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#6fbf68"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Panels</text><line x1="134.8" y1="20" x2="134.8" y2="56" stroke="#2b2636" stroke-width="1"/><text x="166.8" y="44" font-size="17" fill="#a1a1aa">Pages</text><text x="257.8" y="44" font-size="17" fill="#f4f4f5">Widgets</text><rect x="239.8" y="73" width="107.4" height="3" fill="#f4f4f5"/><text x="369.2" y="44" font-size="17" fill="#a1a1aa">Fields</text><text x="470.4" y="44" font-size="17" fill="#a1a1aa">Navigation</text><text x="757" y="43.3" font-size="15" fill="#d4d4d8">Typed</text><rect x="697" y="27" width="46" height="22" fill="#6fbf68"/><rect x="721" y="30" width="19" height="16" fill="#15121d"/><line x1="0" y1="76" x2="826" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">FILE</text><text x="794" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">ZONE</text><line x1="0" y1="130" x2="826" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">payout-summary.tsx</text><text x="794" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">orders.detail.side.after</text><line x1="0" y1="194" x2="826" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">order-sla.tsx</text><text x="794" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">orders.list.before</text><line x1="0" y1="258" x2="826" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">offer-badges.tsx</text><text x="794" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">offers.list.after</text><line x1="0" y1="322" x2="826" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#f4f4f5">offer-docs.tsx</text><text x="794" y="359.6" font-size="16" fill="#f4f4f5" text-anchor="end">offers.detail.main.after</text><line x1="0" y1="386" x2="826" y2="386" stroke="#221e2b" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#f4f4f5">vip-note.tsx</text><text x="794" y="423.6" font-size="16" fill="#f4f4f5" text-anchor="end">customers.detail.side</text><line x1="0" y1="450" x2="826" y2="450" stroke="#221e2b" stroke-width="1"/></g></g><rect x="136.5" y="126.5" width="825" height="513" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="88" y="212" width="826" height="514" fill="#15121d" filter="url(#sh)"/><rect x="88" y="212" width="826" height="514" fill="#15121d"/><g transform="translate(88 212)"><g clip-path="url(#c3)"><rect x="24" y="33" width="10" height="10" fill="#f4f4f5"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Backend</text><line x1="145.6" y1="20" x2="145.6" y2="56" stroke="#2b2636" stroke-width="1"/><text x="177.6" y="44" font-size="17" fill="#f4f4f5">Hooks</text><rect x="159.6" y="73" width="87" height="3" fill="#f4f4f5"/><text x="268.6" y="44" font-size="17" fill="#a1a1aa">Routes</text><text x="369.8" y="44" font-size="17" fill="#a1a1aa">Modules</text><text x="802" y="43.3" font-size="15" fill="#71717a" text-anchor="end">src/</text><line x1="0" y1="76" x2="826" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">NAME</text><text x="794" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">WORKFLOW</text><line x1="0" y1="130" x2="826" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">sellerApproved</text><text x="794" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">approveSellerWorkflow</text><line x1="0" y1="194" x2="826" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">orderGroupCreated</text><text x="794" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">completeCartWithSplitOrdersWorkflow</text><line x1="0" y1="258" x2="826" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">offersCreated</text><text x="794" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">createOffersWorkflow</text><line x1="0" y1="322" x2="826" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#f4f4f5">productChangeConfirmed</text><text x="794" y="359.6" font-size="16" fill="#f4f4f5" text-anchor="end">confirmProductChangeWorkflow</text><line x1="0" y1="386" x2="826" y2="386" stroke="#221e2b" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#f4f4f5">payoutCreated</text><text x="794" y="423.6" font-size="16" fill="#f4f4f5" text-anchor="end">createPayoutWorkflow</text><line x1="0" y1="450" x2="826" y2="450" stroke="#221e2b" stroke-width="1"/></g></g><rect x="88.5" y="212.5" width="825" height="513" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="298" width="826" height="514" fill="#15121d" filter="url(#sh)"/><rect x="40" y="298" width="826" height="514" fill="#15121d"/><g transform="translate(40 298)"><g clip-path="url(#c4)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Extensions</text><line x1="178" y1="20" x2="178" y2="56" stroke="#2b2636" stroke-width="1"/><text x="210" y="44" font-size="17" fill="#f4f4f5">All</text><rect x="192" y="73" width="66.6" height="3" fill="#f4f4f5"/><text x="280.6" y="44" font-size="17" fill="#a1a1aa">Backend</text><text x="392" y="44" font-size="17" fill="#a1a1aa">Panels</text><text x="721" y="43.3" font-size="15" fill="#d4d4d8">Typecheck</text><rect x="661" y="27" width="46" height="22" fill="#6fbf68"/><rect x="685" y="30" width="19" height="16" fill="#15121d"/><line x1="0" y1="76" x2="826" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">PATH</text><text x="446" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">ZONE</text><text x="574" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">TARGET</text><line x1="0" y1="130" x2="826" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#a78bfa"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">src/workflows/hooks/seller-approved.ts</text><rect x="446" y="147" width="60" height="30" fill="#1f1b29"/><text x="458" y="167.3" font-size="15" fill="#a1a1aa">hook</text><text x="574" y="167.6" font-size="16" fill="#f4f4f5">sellerApproved</text><line x1="0" y1="194" x2="826" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">src/api/vendor/sellers/documents/route.ts</text><rect x="446" y="211" width="69" height="30" fill="#1f1b29"/><text x="458" y="231.3" font-size="15" fill="#a1a1aa">route</text><text x="574" y="231.6" font-size="16" fill="#d4d4d8">/vendor/sellers/…</text><line x1="0" y1="258" x2="826" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">src/modules/subscription/index.ts</text><rect x="446" y="275" width="78" height="30" fill="#1f1b29"/><text x="458" y="295.3" font-size="15" fill="#a1a1aa">module</text><text x="574" y="295.6" font-size="16" fill="#d4d4d8">↔ seller</text><line x1="0" y1="322" x2="826" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#f4f4f5">medusa-config.ts</text><rect x="446" y="339" width="69" height="30" fill="#1f1b29"/><text x="458" y="359.3" font-size="15" fill="#a1a1aa">field</text><text x="574" y="359.6" font-size="16" fill="#d4d4d8">Product.is_featured</text><line x1="0" y1="386" x2="826" y2="386" stroke="#221e2b" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#f4f4f5">src/routes/reports/page.tsx</text><rect x="446" y="403" width="60" height="30" fill="#1f1b29"/><text x="458" y="423.3" font-size="15" fill="#a1a1aa">page</text><text x="574" y="423.6" font-size="16" fill="#d4d4d8">/reports</text><line x1="0" y1="450" x2="826" y2="450" stroke="#221e2b" stroke-width="1"/><text x="32" y="487.6" font-size="16" fill="#f4f4f5">src/widgets/payout-summary.tsx</text><rect x="446" y="467" width="78" height="30" fill="#1f1b29"/><text x="458" y="487.3" font-size="15" fill="#a1a1aa">widget</text><text x="574" y="487.6" font-size="16" fill="#d4d4d8">orders.detail.side</text><line x1="0" y1="514" x2="826" y2="514" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="298.5" width="825" height="513" fill="none" stroke="#2b2636" stroke-width="1"/>+</svg>\ No newline at end of filediff --git a/apps/docs/images/figures/extension-zones-light.svg b/apps/docs/images/figures/extension-zones-light.svgnew file mode 100644index 000000000..eed44b9da--- /dev/null+++ b/apps/docs/images/figures/extension-zones-light.svg@@ -0,0 +1,5 @@+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="870" viewBox="0 0 1040 870" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="Stacked panels for Blocks, Panels, and Backend, with an Extensions table in front listing one file per zone: a workflow hook, an API route, a module, a custom field, a page, and a widget, each with its typed target.">+<title>Stacked panels for Blocks, Panels, and Backend, with an Extensions table in front listing one file per zone: a workflow hook, an API route, a module, a custom field, a page, and a widget, each with its typed target.</title>+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="826" height="514"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="826" height="514"/></clipPath><clipPath id="c3"><rect x="0" y="0" width="826" height="514"/></clipPath><clipPath id="c4"><rect x="0" y="0" width="826" height="514"/></clipPath></defs>+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="528.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="0" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="0" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="88" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="176" width="88" height="88" fill="url(#dt)"/><rect x="440" y="176" width="88" height="88" fill="url(#dt)"/><rect x="704.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="264" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="528" y="352" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="440" width="88" height="88" fill="url(#dt)"/><rect x="0" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="0" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="176.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="616" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="1056.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="792" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968" y="528" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="352" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="792" y="616" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="704" width="88" height="88" fill="url(#dt)"/><rect x="0" y="704" width="88" height="88" fill="url(#dt)"/><rect x="704.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="792.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="792" width="88" height="88" fill="url(#dt)"/><rect x="176" y="792" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="792" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="264" y="792" width="88" height="88" fill="#e4e4e7"/><rect x="264" y="792" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="440.5" y="792.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704.5" y="792.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="792.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="792" width="88" height="88" fill="url(#dt)"/><rect x="176" y="880" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="880" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="264" y="880" width="88" height="88" fill="url(#dt)"/><rect x="352" y="880" width="88" height="88" fill="#e4e4e7"/><rect x="352" y="880" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="440" y="880" width="88" height="88" fill="#e4e4e7"/><rect x="440" y="880" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="528.5" y="880.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616" y="880" width="88" height="88" fill="#e4e4e7"/><rect x="616" y="880" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="704" y="880" width="88" height="88" fill="url(#dt)"/><rect x="968" y="880" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="880" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="184" y="40" width="826" height="514" fill="#ffffff" filter="url(#sh)"/><rect x="184" y="40" width="826" height="514" fill="#ffffff"/><g transform="translate(184 40)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#c2680c"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Blocks</text><line x1="134.8" y1="20" x2="134.8" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="166.8" y="44" font-size="17" fill="#18181b">Installed</text><rect x="148.8" y="73" width="127.8" height="3" fill="#18181b"/><text x="298.6" y="44" font-size="17" fill="#71717a">Registry</text><text x="721" y="43.3" font-size="15" fill="#3f3f46">Overwrite</text><rect x="661" y="27" width="46" height="22" fill="#d4d4d8"/><rect x="664" y="30" width="19" height="16" fill="#ffffff"/><line x1="0" y1="76" x2="826" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">BLOCK</text><text x="332" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">FILES</text><text x="794" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">UPSTREAM</text><line x1="0" y1="130" x2="826" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">wishlist</text><text x="332" y="167.6" font-size="16" fill="#18181b">9</text><rect x="692.4" y="146" width="101.6" height="32" fill="#f4f4f5"/><rect x="704.4" y="157" width="10" height="10" fill="#3f7d3a"/><text x="726.4" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">SYNCED</text><line x1="0" y1="194" x2="826" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">algolia</text><text x="332" y="231.6" font-size="16" fill="#18181b">6</text><rect x="711.6" y="210" width="82.4" height="32" fill="#f4f4f5"/><rect x="723.6" y="221" width="10" height="10" fill="#c2680c"/><text x="745.6" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">DIFF</text><line x1="0" y1="258" x2="826" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">vendor-chat</text><text x="332" y="295.6" font-size="16" fill="#18181b">21</text><rect x="692.4" y="274" width="101.6" height="32" fill="#f4f4f5"/><rect x="704.4" y="285" width="10" height="10" fill="#3f7d3a"/><text x="726.4" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">SYNCED</text><line x1="0" y1="322" x2="826" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#18181b">requests</text><text x="332" y="359.6" font-size="16" fill="#18181b">17</text><rect x="692.4" y="338" width="101.6" height="32" fill="#f4f4f5"/><rect x="704.4" y="349" width="10" height="10" fill="#3f7d3a"/><text x="726.4" y="358.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">SYNCED</text><line x1="0" y1="386" x2="826" y2="386" stroke="#ededf0" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#18181b">vendor-notifications</text><text x="332" y="423.6" font-size="16" fill="#18181b">11</text><rect x="711.6" y="402" width="82.4" height="32" fill="#f4f4f5"/><rect x="723.6" y="413" width="10" height="10" fill="#c2680c"/><text x="745.6" y="422.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">DIFF</text><line x1="0" y1="450" x2="826" y2="450" stroke="#ededf0" stroke-width="1"/><text x="32" y="487.6" font-size="16" fill="#18181b">meilisearch</text><text x="332" y="487.6" font-size="16" fill="#18181b">6</text><rect x="692.4" y="466" width="101.6" height="32" fill="#f4f4f5"/><rect x="704.4" y="477" width="10" height="10" fill="#3f7d3a"/><text x="726.4" y="486.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">SYNCED</text><line x1="0" y1="514" x2="826" y2="514" stroke="#ededf0" stroke-width="1"/></g></g><rect x="184.5" y="40.5" width="825" height="513" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="136" y="126" width="826" height="514" fill="#ffffff" filter="url(#sh)"/><rect x="136" y="126" width="826" height="514" fill="#ffffff"/><g transform="translate(136 126)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#3f7d3a"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Panels</text><line x1="134.8" y1="20" x2="134.8" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="166.8" y="44" font-size="17" fill="#71717a">Pages</text><text x="257.8" y="44" font-size="17" fill="#18181b">Widgets</text><rect x="239.8" y="73" width="107.4" height="3" fill="#18181b"/><text x="369.2" y="44" font-size="17" fill="#71717a">Fields</text><text x="470.4" y="44" font-size="17" fill="#71717a">Navigation</text><text x="757" y="43.3" font-size="15" fill="#3f3f46">Typed</text><rect x="697" y="27" width="46" height="22" fill="#3f7d3a"/><rect x="721" y="30" width="19" height="16" fill="#ffffff"/><line x1="0" y1="76" x2="826" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">FILE</text><text x="794" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">ZONE</text><line x1="0" y1="130" x2="826" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">payout-summary.tsx</text><text x="794" y="167.6" font-size="16" fill="#18181b" text-anchor="end">orders.detail.side.after</text><line x1="0" y1="194" x2="826" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">order-sla.tsx</text><text x="794" y="231.6" font-size="16" fill="#18181b" text-anchor="end">orders.list.before</text><line x1="0" y1="258" x2="826" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">offer-badges.tsx</text><text x="794" y="295.6" font-size="16" fill="#18181b" text-anchor="end">offers.list.after</text><line x1="0" y1="322" x2="826" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#18181b">offer-docs.tsx</text><text x="794" y="359.6" font-size="16" fill="#18181b" text-anchor="end">offers.detail.main.after</text><line x1="0" y1="386" x2="826" y2="386" stroke="#ededf0" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#18181b">vip-note.tsx</text><text x="794" y="423.6" font-size="16" fill="#18181b" text-anchor="end">customers.detail.side</text><line x1="0" y1="450" x2="826" y2="450" stroke="#ededf0" stroke-width="1"/></g></g><rect x="136.5" y="126.5" width="825" height="513" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="88" y="212" width="826" height="514" fill="#ffffff" filter="url(#sh)"/><rect x="88" y="212" width="826" height="514" fill="#ffffff"/><g transform="translate(88 212)"><g clip-path="url(#c3)"><rect x="24" y="33" width="10" height="10" fill="#18181b"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Backend</text><line x1="145.6" y1="20" x2="145.6" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="177.6" y="44" font-size="17" fill="#18181b">Hooks</text><rect x="159.6" y="73" width="87" height="3" fill="#18181b"/><text x="268.6" y="44" font-size="17" fill="#71717a">Routes</text><text x="369.8" y="44" font-size="17" fill="#71717a">Modules</text><text x="802" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">src/</text><line x1="0" y1="76" x2="826" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">NAME</text><text x="794" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">WORKFLOW</text><line x1="0" y1="130" x2="826" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">sellerApproved</text><text x="794" y="167.6" font-size="16" fill="#18181b" text-anchor="end">approveSellerWorkflow</text><line x1="0" y1="194" x2="826" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">orderGroupCreated</text><text x="794" y="231.6" font-size="16" fill="#18181b" text-anchor="end">completeCartWithSplitOrdersWorkflow</text><line x1="0" y1="258" x2="826" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">offersCreated</text><text x="794" y="295.6" font-size="16" fill="#18181b" text-anchor="end">createOffersWorkflow</text><line x1="0" y1="322" x2="826" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#18181b">productChangeConfirmed</text><text x="794" y="359.6" font-size="16" fill="#18181b" text-anchor="end">confirmProductChangeWorkflow</text><line x1="0" y1="386" x2="826" y2="386" stroke="#ededf0" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#18181b">payoutCreated</text><text x="794" y="423.6" font-size="16" fill="#18181b" text-anchor="end">createPayoutWorkflow</text><line x1="0" y1="450" x2="826" y2="450" stroke="#ededf0" stroke-width="1"/></g></g><rect x="88.5" y="212.5" width="825" height="513" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="298" width="826" height="514" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="298" width="826" height="514" fill="#ffffff"/><g transform="translate(40 298)"><g clip-path="url(#c4)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Extensions</text><line x1="178" y1="20" x2="178" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="210" y="44" font-size="17" fill="#18181b">All</text><rect x="192" y="73" width="66.6" height="3" fill="#18181b"/><text x="280.6" y="44" font-size="17" fill="#71717a">Backend</text><text x="392" y="44" font-size="17" fill="#71717a">Panels</text><text x="721" y="43.3" font-size="15" fill="#3f3f46">Typecheck</text><rect x="661" y="27" width="46" height="22" fill="#3f7d3a"/><rect x="685" y="30" width="19" height="16" fill="#ffffff"/><line x1="0" y1="76" x2="826" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">PATH</text><text x="446" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">ZONE</text><text x="574" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">TARGET</text><line x1="0" y1="130" x2="826" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#7c3aed"/><text x="32" y="167.6" font-size="16" fill="#18181b">src/workflows/hooks/seller-approved.ts</text><rect x="446" y="147" width="60" height="30" fill="#f4f4f5"/><text x="458" y="167.3" font-size="15" fill="#71717a">hook</text><text x="574" y="167.6" font-size="16" fill="#18181b">sellerApproved</text><line x1="0" y1="194" x2="826" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">src/api/vendor/sellers/documents/route.ts</text><rect x="446" y="211" width="69" height="30" fill="#f4f4f5"/><text x="458" y="231.3" font-size="15" fill="#71717a">route</text><text x="574" y="231.6" font-size="16" fill="#3f3f46">/vendor/sellers/…</text><line x1="0" y1="258" x2="826" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">src/modules/subscription/index.ts</text><rect x="446" y="275" width="78" height="30" fill="#f4f4f5"/><text x="458" y="295.3" font-size="15" fill="#71717a">module</text><text x="574" y="295.6" font-size="16" fill="#3f3f46">↔ seller</text><line x1="0" y1="322" x2="826" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#18181b">medusa-config.ts</text><rect x="446" y="339" width="69" height="30" fill="#f4f4f5"/><text x="458" y="359.3" font-size="15" fill="#71717a">field</text><text x="574" y="359.6" font-size="16" fill="#3f3f46">Product.is_featured</text><line x1="0" y1="386" x2="826" y2="386" stroke="#ededf0" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#18181b">src/routes/reports/page.tsx</text><rect x="446" y="403" width="60" height="30" fill="#f4f4f5"/><text x="458" y="423.3" font-size="15" fill="#71717a">page</text><text x="574" y="423.6" font-size="16" fill="#3f3f46">/reports</text><line x1="0" y1="450" x2="826" y2="450" stroke="#ededf0" stroke-width="1"/><text x="32" y="487.6" font-size="16" fill="#18181b">src/widgets/payout-summary.tsx</text><rect x="446" y="467" width="78" height="30" fill="#f4f4f5"/><text x="458" y="487.3" font-size="15" fill="#71717a">widget</text><text x="574" y="487.6" font-size="16" fill="#3f3f46">orders.detail.side</text><line x1="0" y1="514" x2="826" y2="514" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="298.5" width="825" height="513" fill="none" stroke="#e4e4e7" stroke-width="1"/>+</svg>\ No newline at end of filediff --git a/apps/docs/images/figures/order-split-dark.svg b/apps/docs/images/figures/order-split-dark.svgnew file mode 100644index 000000000..c868c7155--- /dev/null+++ b/apps/docs/images/figures/order-split-dark.svg@@ -0,0 +1,5 @@+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="610" viewBox="0 0 1040 610" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A cart with items from two sellers becomes order group #G98, split into order #100 for ACME and order #99 for GLOBEX, each with its own status, commission, and payout.">+<title>A cart with items from two sellers becomes order group #G98, split into order #100 for ACME and order #99 for GLOBEX, each with its own status, commission, and payout.</title>+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="387"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="387"/></clipPath></defs>+<rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="88" width="88" height="88" fill="#1d1926"/><rect x="528" y="88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="792.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="176.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704" y="176" width="88" height="88" fill="url(#dt)"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="176" width="88" height="88" fill="#1d1926"/><rect x="1056" y="176" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="-87.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="264" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="264" width="88" height="88" fill="#1d1926"/><rect x="1056" y="264" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="-87.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="352" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="352" width="88" height="88" fill="url(#dt)"/><rect x="176.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0" y="528" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="528" width="88" height="88" fill="#1d1926"/><rect x="352" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="url(#dt)"/><rect x="0" y="616" width="88" height="88" fill="#1d1926"/><rect x="0" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="100" y="82" width="900" height="387" fill="#15121d" filter="url(#sh)"/><rect x="100" y="82" width="900" height="387" fill="#15121d"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#f2a14b"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Cart</text><line x1="113.2" y1="20" x2="113.2" y2="56" stroke="#2b2636" stroke-width="1"/><text x="145.2" y="44" font-size="17" fill="#f4f4f5">Items</text><rect x="127.2" y="73" width="87" height="3" fill="#f4f4f5"/><text x="236.2" y="44" font-size="17" fill="#a1a1aa">Shipping</text><text x="357.8" y="44" font-size="17" fill="#a1a1aa">Payment</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">cart_01JD8Q</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">ITEM</text><text x="332" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">SELLER</text><text x="652" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">QTY</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">PRICE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">Linen shirt</text><text x="332" y="167.6" font-size="16" fill="#f4f4f5">ACME</text><text x="652" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">1</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 47.00</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">Desk lamp</text><text x="332" y="231.6" font-size="16" fill="#f4f4f5">GLOBEX</text><text x="652" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">1</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 40.00</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">Shipping</text><text x="868" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 0.00</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="386" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="168" width="900" height="387" fill="#15121d" filter="url(#sh)"/><rect x="40" y="168" width="900" height="387" fill="#15121d"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Orders</text><line x1="134.8" y1="20" x2="134.8" y2="56" stroke="#2b2636" stroke-width="1"/><text x="166.8" y="44" font-size="17" fill="#a1a1aa">All</text><text x="237.4" y="44" font-size="17" fill="#f4f4f5">Groups</text><rect x="219.4" y="73" width="97.2" height="3" fill="#f4f4f5"/><text x="338.6" y="44" font-size="17" fill="#a1a1aa">Returns</text><text x="741" y="43.3" font-size="15" fill="#d4d4d8">Split by seller</text><rect x="681" y="27" width="46" height="22" fill="#6fbf68"/><rect x="705" y="30" width="19" height="16" fill="#15121d"/><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">ORDER</text><text x="152" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">STORE</text><text x="302" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">STATUS</text><text x="642" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">COMMISSION</text><text x="752" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">PAYOUT</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">TOTAL</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#a78bfa"/><polygon points="32,158.5 42,158.5 37,165.5" fill="#d4d4d8"/><text x="54" y="167.6" font-size="16" fill="#f4f4f5">#G98</text><text x="152" y="167.6" font-size="16" fill="#f4f4f5">2 stores</text><text x="642" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 8.70</text><text x="752" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 78.30</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 87.00</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="64" y="231.6" font-size="16" fill="#f4f4f5">#100</text><text x="152" y="231.6" font-size="16" fill="#f4f4f5">ACME</text><rect x="302" y="210" width="168.8" height="32" fill="#1f1b29"/><rect x="314" y="221" width="10" height="10" fill="#f0735a"/><text x="336" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">NOT FULFILLED</text><text x="642" y="231.6" font-size="16" fill="#a1a1aa" text-anchor="end">€ 4.70</text><text x="752" y="231.6" font-size="16" fill="#a1a1aa" text-anchor="end">€ 42.30</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 47.00</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="64" y="295.6" font-size="16" fill="#f4f4f5">#99</text><text x="152" y="295.6" font-size="16" fill="#f4f4f5">GLOBEX</text><rect x="302" y="274" width="130.4" height="32" fill="#1f1b29"/><rect x="314" y="285" width="10" height="10" fill="#6fbf68"/><text x="336" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">DELIVERED</text><text x="642" y="295.6" font-size="16" fill="#a1a1aa" text-anchor="end">€ 4.00</text><text x="752" y="295.6" font-size="16" fill="#a1a1aa" text-anchor="end">€ 36.00</text><text x="868" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 40.00</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/><polygon points="34,349 41,354 34,359" fill="#d4d4d8"/><text x="54" y="359.6" font-size="16" fill="#a1a1aa">#G97</text><text x="152" y="359.6" font-size="16" fill="#a1a1aa">1 store</text><text x="642" y="359.6" font-size="16" fill="#a1a1aa" text-anchor="end">€ 2.10</text><text x="752" y="359.6" font-size="16" fill="#a1a1aa" text-anchor="end">€ 18.90</text><text x="868" y="359.6" font-size="16" fill="#a1a1aa" text-anchor="end">€ 21.00</text><line x1="0" y1="386" x2="900" y2="386" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="386" fill="none" stroke="#2b2636" stroke-width="1"/>+</svg>\ No newline at end of filediff --git a/apps/docs/images/figures/order-split-light.svg b/apps/docs/images/figures/order-split-light.svgnew file mode 100644index 000000000..2386458ea--- /dev/null+++ b/apps/docs/images/figures/order-split-light.svg@@ -0,0 +1,5 @@+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="610" viewBox="0 0 1040 610" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A cart with items from two sellers becomes order group #G98, split into order #100 for ACME and order #99 for GLOBEX, each with its own status, commission, and payout.">+<title>A cart with items from two sellers becomes order group #G98, split into order #100 for ACME and order #99 for GLOBEX, each with its own status, commission, and payout.</title>+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="387"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="387"/></clipPath></defs>+<rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="88" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="792.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="176.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704" y="176" width="88" height="88" fill="url(#dt)"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="176" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="176" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="-87.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="264" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="264" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="264" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="-87.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="352" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="352" width="88" height="88" fill="url(#dt)"/><rect x="176.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0" y="528" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="352" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="url(#dt)"/><rect x="0" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="0" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="100" y="82" width="900" height="387" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="82" width="900" height="387" fill="#ffffff"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#c2680c"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Cart</text><line x1="113.2" y1="20" x2="113.2" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="145.2" y="44" font-size="17" fill="#18181b">Items</text><rect x="127.2" y="73" width="87" height="3" fill="#18181b"/><text x="236.2" y="44" font-size="17" fill="#71717a">Shipping</text><text x="357.8" y="44" font-size="17" fill="#71717a">Payment</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">cart_01JD8Q</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">ITEM</text><text x="332" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">SELLER</text><text x="652" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">QTY</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">PRICE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">Linen shirt</text><text x="332" y="167.6" font-size="16" fill="#18181b">ACME</text><text x="652" y="167.6" font-size="16" fill="#18181b" text-anchor="end">1</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">€ 47.00</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">Desk lamp</text><text x="332" y="231.6" font-size="16" fill="#18181b">GLOBEX</text><text x="652" y="231.6" font-size="16" fill="#18181b" text-anchor="end">1</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">€ 40.00</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">Shipping</text><text x="868" y="295.6" font-size="16" fill="#18181b" text-anchor="end">€ 0.00</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="386" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="168" width="900" height="387" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="168" width="900" height="387" fill="#ffffff"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Orders</text><line x1="134.8" y1="20" x2="134.8" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="166.8" y="44" font-size="17" fill="#71717a">All</text><text x="237.4" y="44" font-size="17" fill="#18181b">Groups</text><rect x="219.4" y="73" width="97.2" height="3" fill="#18181b"/><text x="338.6" y="44" font-size="17" fill="#71717a">Returns</text><text x="741" y="43.3" font-size="15" fill="#3f3f46">Split by seller</text><rect x="681" y="27" width="46" height="22" fill="#3f7d3a"/><rect x="705" y="30" width="19" height="16" fill="#ffffff"/><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">ORDER</text><text x="152" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">STORE</text><text x="302" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">STATUS</text><text x="642" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">COMMISSION</text><text x="752" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">PAYOUT</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">TOTAL</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#7c3aed"/><polygon points="32,158.5 42,158.5 37,165.5" fill="#3f3f46"/><text x="54" y="167.6" font-size="16" fill="#18181b">#G98</text><text x="152" y="167.6" font-size="16" fill="#18181b">2 stores</text><text x="642" y="167.6" font-size="16" fill="#18181b" text-anchor="end">€ 8.70</text><text x="752" y="167.6" font-size="16" fill="#18181b" text-anchor="end">€ 78.30</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">€ 87.00</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="64" y="231.6" font-size="16" fill="#18181b">#100</text><text x="152" y="231.6" font-size="16" fill="#18181b">ACME</text><rect x="302" y="210" width="168.8" height="32" fill="#f4f4f5"/><rect x="314" y="221" width="10" height="10" fill="#b3361f"/><text x="336" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">NOT FULFILLED</text><text x="642" y="231.6" font-size="16" fill="#71717a" text-anchor="end">€ 4.70</text><text x="752" y="231.6" font-size="16" fill="#71717a" text-anchor="end">€ 42.30</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">€ 47.00</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="64" y="295.6" font-size="16" fill="#18181b">#99</text><text x="152" y="295.6" font-size="16" fill="#18181b">GLOBEX</text><rect x="302" y="274" width="130.4" height="32" fill="#f4f4f5"/><rect x="314" y="285" width="10" height="10" fill="#3f7d3a"/><text x="336" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">DELIVERED</text><text x="642" y="295.6" font-size="16" fill="#71717a" text-anchor="end">€ 4.00</text><text x="752" y="295.6" font-size="16" fill="#71717a" text-anchor="end">€ 36.00</text><text x="868" y="295.6" font-size="16" fill="#18181b" text-anchor="end">€ 40.00</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/><polygon points="34,349 41,354 34,359" fill="#3f3f46"/><text x="54" y="359.6" font-size="16" fill="#71717a">#G97</text><text x="152" y="359.6" font-size="16" fill="#71717a">1 store</text><text x="642" y="359.6" font-size="16" fill="#71717a" text-anchor="end">€ 2.10</text><text x="752" y="359.6" font-size="16" fill="#71717a" text-anchor="end">€ 18.90</text><text x="868" y="359.6" font-size="16" fill="#71717a" text-anchor="end">€ 21.00</text><line x1="0" y1="386" x2="900" y2="386" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="386" fill="none" stroke="#e4e4e7" stroke-width="1"/>+</svg>\ No newline at end of filediff --git a/apps/docs/learn/architecture.mdx b/apps/docs/learn/architecture.mdxindex 92649ecdd..c75ef946e 100644--- a/apps/docs/learn/architecture.mdx+++ b/apps/docs/learn/architecture.mdx@@ -1,350 +1,253 @@---title: "Architecture"-description: "How Mercur is put together: the runtime layers, the boundary between the marketplace platform and your own code, and the zones you extend."+description: "What runs where in a Mercur project, which package does what, and where your own code goes."----Mercur is an open-source marketplace platform. It gives you a multi-vendor-commerce backend, an admin panel, and a vendor portal that you deploy on your own-infrastructure and change at the source level.--It is not a hosted service you integrate with, and it is not a starter kit you-finish yourself. Mercur is a running system on day one, with defined seams for-the parts every marketplace does differently: onboarding rules, commission logic,-approval policy, back-office integrations, and the screens your teams work in.--This page describes those layers and those seams. If you are evaluating Mercur,-the two questions it answers are **what runs where** and **where does my code go**.--## Design principles--Everything below follows from four decisions.--- **You run it.** MIT-licensed, PostgreSQL, Node. No vendor in the request path, no GMV fee, no proprietary runtime. Self-host, or deploy to any cloud that runs a Node process and a database.-- **Extension over configuration.** Instead of hundreds of settings, the platform exposes typed extension zones: workflow hooks, API routes, modules, custom fields, pages, and widgets. When a zone isn't enough, the source is yours to change.-- **Marketplace on top of commerce, not instead of it.** Products, carts, orders, payments, and fulfillment are handled by [Medusa](https://medusajs.com), a mature commerce engine. Mercur adds only what multi-vendor requires: sellers, offers, order splitting, commissions, payouts, and governance.-- **Governance is structural.** Role scoping, the product change pipeline, and exact-precision money arithmetic are properties of the architecture, not features you enable.--## The layers--Mercur is a single deployable backend with three API surfaces, plus two panel-applications that are ordinary clients of those APIs.--```mermaid-graph TD- subgraph Clients- A[Admin Panel<br/>React]- B[Vendor Portal<br/>React]- C[Storefront<br/>any framework]- D[Your services<br/>ERP · PIM · agents]- end-- subgraph "Backend — one Node process"- E["/admin/*"]- F["/vendor/*"]- G["/store/*"]- H[Marketplace domain<br/>sellers · offers · commissions · payouts · governance]- I[Commerce domain<br/>products · carts · orders · payments · fulfillment]- end-- J[(PostgreSQL)]- K[Redis · event bus, workflow engine, cache]- L[Providers<br/>payment · payout · fulfillment · notification · search]-- A --> E- B --> F- C --> G- D --> E- E --> H- F --> H- G --> H- H --> I- I --> J- H --> J- H --> K- H --> L-```--### Data+Mercur is a [Medusa](https://medusajs.com) application with a marketplace layer on top. One Node process serves three HTTP APIs, two React panels and your storefront call it through a typed client, and PostgreSQL stores all data. This page lists each piece, the package it ships in, and where your own code fits.-One PostgreSQL database. Every domain owns its own tables and never reaches into-another's; relationships across domains are declared explicitly as links (see-[Links](#links)). That isolation is what makes a domain replaceable, and what-keeps a schema change local instead of platform-wide.+<img className="block dark:hidden" src="/images/figures/architecture-layers-light.svg" alt="Mercur's architecture: the admin and vendor panels, a storefront, and your services call the backend through @mercurjs/client. The backend exposes /admin, /vendor, and /store and runs marketplace modules from @mercurjs/core beside Medusa's commerce modules and your own code, over PostgreSQL, Redis, and providers." />+<img className="hidden dark:block" src="/images/figures/architecture-layers-dark.svg" alt="Mercur's architecture: the admin and vendor panels, a storefront, and your services call the backend through @mercurjs/client. The backend exposes /admin, /vendor, and /store and runs marketplace modules from @mercurjs/core beside Medusa's commerce modules and your own code, over PostgreSQL, Redis, and providers." />-Redis backs the event bus, the workflow engine, and caching in production. In-development both fall back to in-memory implementations, so a laptop needs-nothing but Postgres.+## How a request runs-### Domain+Mercur keeps Medusa’s layers as they are, so [Medusa’s architecture guide](https://docs.medusajs.com/learn/introduction/architecture) applies to every Mercur project. A request passes through four layers:-The domain layer is where marketplace behaviour lives: seller accounts and-members, offers against a shared product catalog, commission rules and their-resolution, payout accounts and transfers, order groups, the product change-pipeline. It calls into the commerce domain for anything commerce already does.+1. **API route**: an HTTP handler under `/admin`, `/vendor`, or `/store`. Middleware authenticates the caller first; on `/vendor` it also resolves the caller’s seller before any handler runs, including handlers you add.+2. **Workflow**: the handler runs a workflow for every write. Each step has a compensation function, so when a step fails, the steps before it roll back.+3. **Module**: workflow steps call module services. A module owns its tables and never imports another module.+4. **Data**: every module stores its tables in the same PostgreSQL database. Links record relationships between modules without foreign keys between their tables.-Two things about this layer matter to an architect:+Reads skip the workflow layer. Handlers call Medusa’s [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), which follows links across modules in one call.-- **It is not a wrapper.** Mercur does not proxy or re-implement commerce endpoints. Marketplace concepts are first-class records with their own lifecycle, joined to commerce records through links.-- **Your own domains sit beside it.** A module you write, a module Mercur ships, and a module Medusa ships are the same kind of object, registered the same way, with the same access to the container, the event bus, and the workflow engine. There is no privileged inner ring.+Checkout uses all four layers in a single request. `completeCartWithSplitOrdersWorkflow` groups the cart’s items by seller, creates one order per seller under an order group, and refreshes each order’s commission lines. If a step fails, the workflow rolls back and the cart stays open.-### API+<img className="block dark:hidden" src="/images/figures/order-split-light.svg" alt="A cart with items from two sellers becomes order group #G98, split into order #100 for ACME and order #99 for GLOBEX, each with its own status, commission, and payout." />+<img className="hidden dark:block" src="/images/figures/order-split-dark.svg" alt="A cart with items from two sellers becomes order group #G98, split into order #100 for ACME and order #99 for GLOBEX, each with its own status, commission, and payout." />-Three HTTP surfaces, one per audience, separated because their authorization-models differ, not because their data does.+## Backend packages-| Surface | Path | Audience | Scoping |-| ---------- | ----------- | --------------------- | ------------------------------------------------------------------ |-| **Admin** | `/admin/*` | Marketplace operators | Platform-wide, gated by role |-| **Vendor** | `/vendor/*` | Sellers | Every request is narrowed to the caller's seller before the handler |-| **Store** | `/store/*` | Customers, storefront | Public catalog and the caller's own cart, orders, and account |+The backend is one Medusa server. Mercur adds a plugin and providers to it; it doesn’t replace or fork the framework.-A route is a thin adapter: middleware authenticates and scopes, a Zod validator-checks the payload, and the handler runs a workflow for writes or the query-engine for reads. Business logic does not live in routes, which is why adding-one is cheap and overriding one is safe. See the-[API conventions](/references/api/conventions).+### Medusa-### Clients+Medusa is the commerce engine: products, pricing, carts, orders, payments, fulfillment, promotions, and the module, workflow, and event system the rest of Mercur is built on. Anything in [Medusa’s documentation](https://docs.medusajs.com/learn) works in a Mercur project.-The admin panel and the vendor portal are separate React applications, not a-templated back office. They talk to the backend through `@mercurjs/client`, a-typed fetch wrapper generated from the real route definitions — including routes-you add — so a backend change that breaks a caller fails at `tsc`, not in-production.+### `@mercurjs/core`-The storefront is deliberately not shipped as a fixed application. Anything that-speaks HTTP consumes the Store API; a reference Next.js storefront is available-to start from.+The marketplace plugin. It contains the marketplace modules (sellers and members, offers, commissions, payouts, product attributes, the product change pipeline, reviews, and custom fields), the workflows that connect them to commerce, the `/vendor` API, and the marketplace routes on `/admin` and `/store`. You register it by wrapping your Medusa config with `withMercur()`:-## The building blocks+```ts medusa-config.ts+import { withMercur } from "@mercurjs/core"-Four primitives compose the domain layer. You use the same four to extend it.+module.exports = withMercur({+ projectConfig: {+ databaseUrl: process.env.DATABASE_URL,+ redisUrl: process.env.REDIS_URL,+ },+})+```-### Modules+Everything else in this file is standard Medusa configuration.-A module owns one domain: its data models, its service, its migrations. Modules-never import each other. That constraint is what lets you swap Mercur's-commission logic for your own, or drop a module you don't use, without a-refactor rippling outward. [Modules →](/resources/best-practices/modules)+[Source](https://github.com/mercurjs/mercur/tree/main/packages/core) · [Platform modules](/platform/store/overview)-### Links+### `@mercurjs/payout-stripe-connect`-A link declares a relationship between records in two modules without either-module knowing about the other. The product–seller link, for example, is what-allowlists which sellers may sell a given product — expressed as a link rather-than a foreign key, so neither the product model nor the seller model is-modified. Your modules link to built-in entities exactly the same way.-[Links →](/resources/best-practices/module-links)+A payout provider built on Stripe Connect. It creates a connected account per seller, returns onboarding links, transfers each seller’s share, and maps Stripe webhooks to payout account statuses.-### Workflows+[Source](https://github.com/mercurjs/mercur/tree/main/packages/providers/payout-stripe-connect) · [Stripe Connect guide](/resources/integrations/stripe-connect)-A workflow is a multi-step operation with automatic compensation: if step five-fails, steps one through four roll back. Anything that crosses domains or must-not half-happen is a workflow — seller approval, payout transfer, and above all-cart completion, which validates the cart, splits it by seller, creates an order-each, allocates payment, and computes commission lines as one atomic unit.+### PostgreSQL and Redis-Workflows also expose **hooks**, which is the primary backend extension zone.-[Workflows →](/resources/best-practices/workflows)+PostgreSQL is the only supported database. The starter `medusa-config.ts` uses Redis for the event bus, the workflow engine, locking, and the cache; Medusa also ships in-memory versions of these modules for development.-### Events and subscribers+## Providers-Workflows emit events; subscribers react asynchronously. Notifications, webhooks-to your systems, search indexing, and payout side effects all hang off this,-which keeps the transactional path short and lets you add behaviour without-touching the workflow that triggered it.-[Subscribers and jobs →](/resources/best-practices/subscribers-and-jobs)+Mercur doesn’t choose your payment gateway, carrier, email service, or search engine. Each integration sits behind a provider interface, and you pick the implementation in `medusa-config.ts`:-## Extension zones+| Concern | Provider interface | Available implementations |+| --- | --- | --- |+| Payments | Medusa payment module | Stripe, or your own provider |+| Seller payouts | Mercur payout module | `@mercurjs/payout-stripe-connect`, a `system` provider for development |+| Fulfillment | Medusa fulfillment module | Manual, or a carrier provider |+| Notifications | Medusa notification module | Local, SendGrid |+| Files | Medusa file module | Local, S3 |+| Authentication | Medusa auth module | Email and password, Google, GitHub |+| Search | Blocks | `algolia`, `meilisearch` |+| Events, workflows, locking, cache | Medusa infrastructure modules | In-memory, Redis |-This is the part that determines what a build actually costs. Mercur exposes six-zones. Each one is typed, each one is additive, and none of them require forking-or patching platform code.+Swapping a provider doesn’t touch marketplace code. A payout provider implements `IPayoutProvider` from `@mercurjs/types`, which has four methods: `createPayoutAccount`, `createOnboarding`, `createPayout`, and `getWebhookActionAndData`. You register it on the payout module:-```mermaid-graph LR- subgraph Backend- A[Workflow hooks<br/>inject steps into existing flows]- B[API routes<br/>add or override endpoints]- C[Modules and links<br/>add domains]- D[Custom fields<br/>extra data on built-in entities]- end- subgraph Panels- E[Pages<br/>new routes]- F[Widgets<br/>components in named zones]- G[Custom field UI<br/>forms · rows · columns]- H[Navigation<br/>reorder · relabel · hide]- end+```ts medusa-config.ts+{+ resolve: "@mercurjs/core/modules/payout",+ options: {+ providers: [+ {+ resolve: "./src/providers/my-payout",+ id: "my-payout",+ options: { apiKey: process.env.PAYOUT_API_KEY },+ },+ ],+ },+}```-### 1. Workflow hooks — change what happens+For the Medusa provider types, see [Medusa’s integrations](https://docs.medusajs.com/resources/integrations).++## Panel packages++The admin panel and the vendor panel are React 18 apps built with Vite and [Medusa UI](https://docs.medusajs.com/ui). They ship as packages that your host apps render, so you upgrade them by bumping a version.-The default way to change platform behaviour. A hook is a declared point inside-an existing workflow where you register your own step. Your step runs inside the-original transaction and participates in its rollback, so you are not-reimplementing the flow to add one rule.+### `@mercurjs/admin` and `@mercurjs/vendor`-```ts src/workflows/hooks/seller-approved.ts-import { approveSellerWorkflow } from "@mercurjs/core/workflows"+`@mercurjs/admin` is the operator panel and `@mercurjs/vendor` is the seller panel. A host app renders the panel and adds its stylesheet:-approveSellerWorkflow.hooks.sellerApproved(- async ({ seller_id }, { container }) => {- await container.resolve("erp").createVendorAccount(seller_id)- }-)+```tsx apps/admin/src/main.tsx+import { createRoot } from "react-dom/client"+import App from "@mercurjs/admin"+import "@mercurjs/admin/index.css"++createRoot(document.getElementById("root")!).render(<App />)```-Reach for a hook when the answer is "the standard flow, plus something."-[Extend a workflow →](/resources/customization/extend-a-workflow)+In development, the host apps run on ports 7000 and 7001. In production you can deploy them as static sites, or serve them from the backend with the `admin-ui` and `vendor-ui` modules of `@mercurjs/core`.-### 2. API routes — add endpoints+[Admin source](https://github.com/mercurjs/mercur/tree/main/packages/admin) · [Vendor source](https://github.com/mercurjs/mercur/tree/main/packages/vendor)-Drop a `route.ts` under `src/api/**` and the endpoint exists. Routes nest under-the built-in ones, so a new resource can hang off an existing entity rather than-living off to the side.+### `@mercurjs/dashboard-sdk`-```-src/api/vendor/sellers/documents/route.ts → GET/POST /vendor/sellers/documents-src/api/vendor/sellers/documents/[id]/route.ts → GET/DELETE /vendor/sellers/documents/:id+A Vite plugin that turns files in a host app into panel extensions. Pages come from `src/routes/**/page.tsx`, widgets from `src/widgets/`, custom-field UI from `src/custom-fields/`, and sidebar changes from `src/_navigation.ts`:++```ts vite.config.ts+import react from "@vitejs/plugin-react"+import { defineConfig } from "vite"+import { mercurDashboardPlugin } from "@mercurjs/dashboard-sdk/vite"++export default defineConfig({+ plugins: [+ react(),+ mercurDashboardPlugin({ medusaConfigPath: "../api/medusa-config.ts" }),+ ],+})```-Your routes get the same treatment as the built-in ones: vendor requests are-already scoped to the caller's seller by the surrounding middleware, and codegen-picks the route up so it appears on the typed client with real request and-response types.+The plugin also writes `extension-targets.d.ts` with every zone id and model name, so a widget that targets a missing zone fails type-checking.-[Create an API route →](/resources/best-practices/api-routes)+[Source](https://github.com/mercurjs/mercur/tree/main/packages/dashboard-sdk) · [Panel extensions](/references/panel-extensions/overview)-### 3. Modules and links — add domains+### `@mercurjs/dashboard-shared`-When the data has its own lifecycle — subscriptions, RMAs, contracts, quotas —-it is a module, not a field. You define the models and service, link the module-to the built-in entities it relates to, and it becomes queryable in the same-graph as everything else. This is how substantial vertical features get built,-and it is the same mechanism Mercur's own domains use.+The UI primitives both panels are built from: forms, tabbed create flows, data tables, route modals and drawers, and query-key helpers. Use them in your own pages so they match the built-in screens.-### 4. Custom fields — add data to built-in entities+[Source](https://github.com/mercurjs/mercur/tree/main/packages/dashboard-shared)-For one plain property on an existing record — `is_featured` on a product,-`tier` on a customer — you declare the field in configuration and the storage,-link, and migration are generated for you.+## Client packages-```ts medusa-config.ts-{- resolve: "@mercurjs/core/modules/custom-fields",- options: {- customFields: {- Product: { is_featured: { type: "boolean", nullable: true } },- },- },-}+Every Mercur client, the panels included, talks to the backend over HTTP through the same typed client.++### `@mercurjs/client`++A typed fetch wrapper. `mercurjs codegen` reads your backend’s API routes, including the ones you add, and writes a `Routes` type. The client turns property access on that type into requests:++```ts src/lib/client.ts+import { createClient, type InferClient } from "@mercurjs/client"+import type { Routes } from "@acme/api/_generated"++export const client: InferClient<Routes> = createClient({+ baseUrl: "http://localhost:9000",+})++const { sellers } = await client.admin.sellers.query({ limit: 20 })```-One row per parent, no lifecycle of its own; anything more is a module.-[Custom fields →](/resources/best-practices/custom-fields)+`.query()` sends a `GET`, `.mutate()` sends a `POST`, and `.delete()` sends a `DELETE`. Because the panels use this client too, a backend change that breaks a caller fails at `tsc` instead of at runtime.++[Source](https://github.com/mercurjs/mercur/tree/main/packages/client) · [Add a typed API route](/resources/tutorials/custom-api-route)-### 5. Panel pages and widgets — change what teams see+### `@mercurjs/types`-The panels are extended by file convention. A file's folder decides what it does,-and there is no manifest to maintain.+Mercur’s entity and HTTP types (sellers, offers, commissions, payouts, order groups), plus re-exports of Medusa’s types. A storefront can type its responses with this package without importing the backend.-| Path | Adds |-| ------------------------ | ------------------------------------- |-| `src/routes/**/page.tsx` | A new page and its route |-| `src/widgets/**` | A component in a named zone on a built-in page |-| `src/custom-fields/**` | Form fields, detail rows, and list columns on a built-in model |-| `src/_navigation.ts` | Sidebar order, labels, and visibility |+[Source](https://github.com/mercurjs/mercur/tree/main/packages/types)-A widget targets a slot on an existing page, which is how you put a payout-summary on the order detail screen without owning that screen:+## Tooling packages-```tsx apps/vendor/src/widgets/payout-summary.tsx-export const config = defineWidgetConfig({ zone: "orders.detail.side.after" })+These packages run on your machine or in CI. None of them run in production.++### `@mercurjs/cli`++The `mercurjs` command. It installs and updates blocks (`add`, `diff`, `search`, `view`), generates route types (`codegen`), and builds plugins and registries:++```bash+bunx @mercurjs/cli@latest add wishlist```-Zone ids, model names, and field ids are generated per panel into-`extension-targets.d.ts`, so a mistargeted extension fails type-checking instead-of silently not rendering.-[Panel extensions →](/references/panel-extensions/overview)+[Source](https://github.com/mercurjs/mercur/tree/main/packages/cli)-### 6. Blocks — install features as source+### `create-mercur-app`-Larger features ship as blocks. The CLI copies the source into your project-rather than adding a dependency, so a block is yours from the moment it lands:-readable, debuggable, and modifiable without waiting on an upstream release.-Updates are explicit — `diff` against the registry and take what you want.+Creates a new project: the API, the admin host app, and the vendor host app in one Turborepo workspace.```bash-bunx @mercurjs/cli@latest add reviews+bunx create-mercur-app@latest```-[Blocks →](/learn/blocks)+[Source](https://github.com/mercurjs/mercur/tree/main/packages/create-mercur-app)++### Blocks-### Choosing a zone+Blocks are features that the CLI copies into your project as source code: modules, workflows, API routes, and panel extensions. Once installed, a block is your code. `mercurjs diff` shows what changed upstream, and you decide what to take. The official registry includes `wishlist`, `algolia`, `meilisearch`, `vendor-chat`, and `requests`, and you can host your own registry.-| You want to… | Use |-| --------------------------------------------------- | ----------------------- |-| Add a rule or side effect to an existing operation | Workflow hook |-| Expose new data or a new operation over HTTP | API route |-| Model something with its own lifecycle | Module and link |-| Store one extra property on a built-in entity | Custom field |-| Show or capture something in the panels | Page, widget, or custom-field UI |-| Adopt a whole feature and own it | Block |+[Blocks](/learn/blocks) · [Registry](/learn/registry)-## Governance+### `@mercurjs/docs`-Multi-vendor means untrusted writers, so the guarantees operators need are built-into the layers rather than layered on.+These docs, bundled into `node_modules` with an `llms.txt` index. Coding agents read them to get the contracts for the Mercur version you installed.-- **Scoping before handling.** Vendor requests are narrowed to the caller's seller in middleware, ahead of any handler. A route cannot accidentally leak across sellers, including a route you add.-- **An immutable change pipeline.** Product edits are recorded as `ProductChange` entries — who changed what, who approved it, when. Low-risk edits auto-confirm; the rest queue for review. The audit trail is the mechanism, not a log written beside it.-- **Exact money.** Commission and payout arithmetic uses arbitrary-precision numbers throughout, so splitting a payment across sellers stays exact.-- **Agents inside the same guardrails.** The typed client, exposed workflows, `llms.txt`, and the MCP server give AI agents structured contracts — subject to the same roles and the same review pipeline as human users.+[Build with AI](/resources/ai/overview)-## How a multi-vendor order flows+## Where your code goes-One cart, several sellers. This is the path that touches every layer.+Your code lives next to Mercur’s in the same project, and nothing requires a fork. Each kind of change has one place to go:-1. The customer adds items from multiple sellers to a single cart (Store API).-2. Cart completion starts the split-order workflow.-3. Items are grouped by seller and an order is created per seller, all under one order group.-4. Commission lines are computed per order from the matching rules.-5. Payment is allocated proportionally across the seller orders.-6. Each seller's share is credited to its payout account, net of commission.-7. Events fire: notifications, webhooks, indexing, and any hook you registered.-8. Sellers fulfill their own orders in the vendor portal; the operator sees all of it in the admin panel.+<img className="block dark:hidden" src="/images/figures/extension-zones-light.svg" alt="Stacked panels for Blocks, Panels, and Backend, with an Extensions table in front listing one file per zone: a workflow hook, an API route, a module, a custom field, a page, and a widget, each with its typed target." />+<img className="hidden dark:block" src="/images/figures/extension-zones-dark.svg" alt="Stacked panels for Blocks, Panels, and Backend, with an Extensions table in front listing one file per zone: a workflow hook, an API route, a module, a custom field, a page, and a widget, each with its typed target." />-Steps 2 through 6 are a single workflow. If any of it fails, none of it happened.+| You want to | Use | Location |+| --- | --- | --- |+| Add a rule or side effect to an existing flow | [Workflow hook](/resources/customization/extend-a-workflow) | `src/workflows/hooks/` |+| Expose data or an operation over HTTP | [API route](/resources/best-practices/api-routes) | `src/api/**/route.ts` |+| Model something with its own lifecycle | [Module](/resources/best-practices/modules) and [link](/resources/best-practices/module-links) | `src/modules/`, `src/links/` |+| Store one extra property on a built-in entity | [Custom field](/resources/best-practices/custom-fields) | `medusa-config.ts` |+| React to something that happened | [Subscriber](/resources/best-practices/subscribers-and-jobs) | `src/subscribers/` |+| Show something in a panel | [Page or widget](/references/panel-extensions/overview) | `src/routes/`, `src/widgets/` |+| Adopt a whole feature | [Block](/learn/blocks) | `bunx @mercurjs/cli@latest add` |-## Stack+## Design decisions-| Concern | Technology |-| ------------------ | -------------------------------------------- |-| Runtime | Node.js 20+, TypeScript |-| Commerce engine | Medusa v2 |-| Database | PostgreSQL |-| Events, cache | Redis (in-memory fallback in development) |-| Panels | React 18, Vite, Medusa UI, TanStack Query |-| Validation, forms | Zod, React Hook Form |-| Build | Turborepo, Bun, tsup |+These decisions explain the shape of the packages above:-Mercur's own code is distributed as `@mercurjs/core`, a Medusa plugin registered-by `withMercur()` in your `medusa-config.ts`. That packaging matters when you-upgrade; it does not change any of the above.+- **A Mercur project is a Medusa project**: Mercur adds modules, routes, and workflows to Medusa and changes none of its layers+- **Modules don’t import each other**: links connect them, so you can replace Mercur’s commission module or remove a module you don’t use+- **Integrations are providers**: payments, payouts, fulfillment, notifications, files, and search each sit behind an interface you implement or swap+- **Seller scoping runs before handlers**: `/vendor` middleware resolves the seller before your code runs+- **Types come from the backend**: codegen reads your routes, the client reads the generated types, and the panels use the client+- **Panels are packages, features are source**: you upgrade the panels by bumping a version, and you own every block you install## Next steps<CardGroup cols={2}><Card title="Platform modules" href="/platform/store/overview">- Data models, workflows, and events for each marketplace domain.- </Card>- <Card title="Panel extensions" href="/references/panel-extensions/overview">- Pages, widgets, custom fields, and navigation.+ Data models, workflows, and events for each marketplace module.</Card><Card title="Extend a workflow" href="/resources/customization/extend-a-workflow">- Inject a step into an existing flow through a hook.+ Run your own step inside an existing flow through a hook.+ </Card>+ <Card title="Panel extensions" href="/references/panel-extensions/overview">+ Add pages, widgets, custom fields, and navigation to the panels.</Card>- <Card title="API reference" href="/references/api/conventions">+ <Card title="API conventions" href="/references/api/conventions">Authentication, seller scoping, and the three API surfaces.</Card></CardGroup>