feat(runtime): every method the editor answers, getStorefront among them

README.md

@@ -37,7 +37,7 @@ One folder per marketplace kind:
 
 | Folder | Kind | Examples |
 | --- | --- | --- |
-| [`plugins/`](examples/plugins) | Plugins | [`arrange-grid`](examples/plugins/arrange-grid) (commands, a UI, storage), [`rename-layers`](examples/plugins/rename-layers) (UI panel, events, storage), [`contrast-checker`](examples/plugins/contrast-checker) (WCAG checks, `findNodes`, `setSelection`), [`pop-palette`](examples/plugins/pop-palette) (paint styles) |
+| [`plugins/`](examples/plugins) | Plugins | [`arrange-grid`](examples/plugins/arrange-grid) (commands, a UI, storage), [`rename-layers`](examples/plugins/rename-layers) (UI panel, events, storage), [`contrast-checker`](examples/plugins/contrast-checker) (WCAG checks, `findNodes`, `setSelection`), [`pop-palette`](examples/plugins/pop-palette) (paint styles), [`storefront-preview`](examples/plugins/storefront-preview) (a File → Export format built on `getStorefront()`) |
 | [`widgets/`](examples/widgets) | Canvas widgets (plugins that register a widget) | [`vote-counter`](examples/widgets/vote-counter), [`poll`](examples/widgets/poll), [`checklist`](examples/widgets/checklist) (named handlers) |
 | [`themes/`](examples/themes) | Theme packs (data-only plugins) | [`comic-themes`](examples/themes/comic-themes) (two light themes), [`comic-noir`](examples/themes/comic-noir) (semi-dark) |
 | [`brushes/`](examples/brushes) | Brush packs | [`comic-inkers`](examples/brushes/comic-inkers): liner, brush pen, stipple |
@@ -51,6 +51,27 @@ Install one from **Main menu → Manage plugins… → Install from file…**, w
 folder (`manifest.json` at the root) or a single-file `.json` bundle:
 `{ "manifest": { … }, "main": "…code…", "ui": "<html>…" }`.
 
+## Importers and exporters
+
+A plugin can add a File → Import or File → Export format in its manifest:
+
+```json
+"contributes": {
+  "importers": [{ "id": "pub", "label": "Publisher (.pub)", "accept": [".pub"] }],
+  "exporters": [{ "id": "ai", "label": "Adobe Illustrator (.ai)", "extension": ".ai" }]
+}
+```
+
+An importer runs with `popcraft.importMode` and `popcraft.importFile` set, and builds the document with the
+editor methods. An exporter runs with `popcraft.exportRequest` set, renders what it needs with `exportNode`, and
+hands the file back with `popcraft.saveExport({ name, bytes })`.
+
+An exporter for a store reads the open page as a storefront with `popcraft.getStorefront()`: each page's HTML with
+the store's data marked rather than filled (`{{page.title}}`, `{{item.price}}`, lists between
+`<!-- pc:each list="Products" schema="commerce.product" as="item" -->` and `<!-- pc:end -->`, forms with
+`data-pc-action`), and the collections it reads with their schema and sample records. It turns those marks into its
+platform's templates; [`storefront-preview`](examples/plugins/storefront-preview) fills them with the samples instead.
+
 ## Publishing to the marketplace
 
 Each item folder holds one of `manifest.json` (a plugin, widget or theme pack), `pack.json` (a brush or

examples/plugins/ecommerce/README.md

@@ -0,0 +1,25 @@
+# Ecommerce
+
+A store for a storefront design. Everything about Shopify lives in this plugin, none of it in the editor:
+
+- **Store** (a tab on the side of the editor): connect a Shopify store by its `.myshopify.com` address and the public
+  Storefront access token (Shopify admin › Sales channels › Headless › your storefront › Storefront API). It is kept
+  with the file, and set as the site environment (`SHOPIFY_STORE_DOMAIN`, `SHOPIFY_STOREFRONT_ACCESS_TOKEN`) that
+  **Publish › Store** deploys a Next.js Commerce store with.
+- **Catalogue**: the store's products as pictures, by category, a product's handle or a search, sorted and limited.
+  Click a picture to place it on the page; **Use in the design** fills the design's products (and categories) with
+  them, so the canvas shows what the store sells.
+- **Make it a store**: the collections a store needs (products, categories, cart, cart lines, menu), with samples,
+  or the store's own products when one is connected.
+- **Checklist**: what the design still needs to sell, the layer to look at, and **Fix** where the plugin can do it
+  (a store form's hidden field: add to cart sends `{{item.variant_id}}`, a cart line's form `{{item.merchandise_id}}`).
+- **Export › Shopify theme (.zip)**: an Online Store 2.0 theme of the design, to upload in Online Store › Themes.
+
+## How it is built
+
+- `contributes.panels` docks the UI (`ui.html`) as the Store tab; `contributes.exporters` adds the theme to Export.
+- The catalogue is read straight from the store's Storefront API (it answers any origin), with the `network`
+  permission. Nothing goes through PopCraft's servers.
+- The design is changed with the editor's own commands: `editCollection`, `editRecords`, `getRecords`, `setControl`,
+  `createNode`, `createImage`, `setSiteEnvironment`; its settings are kept with `setFileData`.
+- The theme is the editor's own Shopify theme target (`getStorefrontFiles('shopify-theme')`), saved with `saveExport`.