@pirateandfox/pagestack 0.0.0-stage → 0.1.0-beta.5

package/README.md

@@ -1,3 +1,318 @@
-# Temporary Holding Version
+# PageStack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A visual editor for Astro sites where pages are a stack of sections. Git-only: saving is a commit,
+the public site stays static, and nothing lives outside the repo.
+
+- The public site stays **fully static**. `astro build` is unchanged.
+- The editor (`/edit/*`, `/api/editor/*`) is on-demand rendered and only exists in `astro dev`
+  or in a build made with `EDITOR=1` (which adds `@astrojs/node`).
+- Pages are JSON documents in the repo (`src/content/pages/<slug>.json`). Saving writes a file
+  (dev) or makes **one commit** through the GitHub API (production). Nothing is stored anywhere else.
+- Login is **passkeys** (WebAuthn). Users' public keys live in a committed `editor-users.json`;
+  the only server secret is `EDITOR_SECRET`. No database, no session store.
+- Live preview renders the real page with the site's own components, in the browser's iframe.
+
+Status: **early beta** (`0.1.0-beta.x`). The API will move; pin a version. See [ROADMAP.md](ROADMAP.md)
+and [CHANGELOG.md](CHANGELOG.md).
+
+## Versions
+
+Published on npm as **`@pirateandfox/pagestack`** (betas under the `beta` dist-tag):
+
+```bash
+npm install @pirateandfox/pagestack@beta
+```
+
+Or install from a git tag and bump the tag to upgrade:
+
+```json
+"dependencies": { "@pirateandfox/pagestack": "github:pirateandfox/pagestack#v0.1.0-beta.4" }
+```
+
+```bash
+npm install            # after changing the tag
+```
+
+Releases are tags `vX.Y.Z[-beta.N]` on `main`; each one has a CHANGELOG entry.
+
+## Install
+
+```js
+// astro.config.mjs
+import pagestack from '@pirateandfox/pagestack';
+
+export default defineConfig({
+  integrations: [
+    pagestack({
+      renderer: './src/components/SectionPage.astro', // renders { page, editing }
+      sections: './src/sections/index.ts',            // exports { schemas, presets }
+      siteName: 'Acme site editor',
+      interactiveSelector: 'summary, .tabs__title, .map__load', // preview elements that keep their own click
+      reservedSlugs: blogSlugs,                        // URLs the site uses some other way
+      auth: 'passkey',                                 // 'passkey' | 'none-behind-proxy' | 'none' (dev only)
+      storage: process.env.EDITOR === '1' ? 'github' : 'local',
+      github: { repo: 'acme/site', branch: 'main', pullRequest: true },
+    }),
+  ],
+});
+```
+
+```bash
+npm run dev                 # editor at http://localhost:4321/edit, saves to the working tree
+EDITOR=1 astro build        # dist/server (node) + dist/client — the editor for a host
+astro build                 # plain static site, no editor code
+```
+
+## What the site provides
+
+### 1. A content model: `src/content/pages/<slug>.json`
+
+```jsonc
+{
+  "title": "Home",
+  "description": "…",
+  "layout": { "footer": "big", "css": ["post-9.css"] },   // opaque to the editor
+  "sections": [
+    { "id": "c8da6f4", "type": "container", "settings": { "backgroundColor": "#fff" },
+      "blocks": [
+        { "id": "1a2b3c4", "type": "heading", "settings": { "text": "Hello", "tag": "h1" } },
+        { "id": "5d6e7f8", "type": "text",    "settings": { "html": "<p>…</p>" } }
+      ] }
+  ]
+}
+```
+
+A page is a tree of nodes. Top-level nodes are *sections*; anything can nest (`blocks`).
+`attrs` is a passthrough for element attributes the editor never shows (class, aria-*).
+`"status": "draft"` keeps a page out of the build; without it the page is published.
+
+To let editors add pages, render them from one catch-all route. A new JSON file is then a new page,
+and drafts are left out:
+
+```astro
+---
+// src/pages/[...page].astro
+import { staticPages } from '@pirateandfox/pagestack/runtime';
+import SectionPage from '../components/SectionPage.astro';
+export const getStaticPaths = () =>
+  staticPages(import.meta.glob('../content/pages/**/*.json', { eager: true }));
+const { page } = Astro.props;
+---
+<SectionPage page={page} />
+```
+
+A site with its own `.astro` file per page keeps working, but pages added in the editor have no
+route until the catch-all exists.
+
+### 2. A block registry: `src/sections/index.ts`
+
+```ts
+import type { BlockSchema, Preset } from '@pirateandfox/pagestack/runtime';
+export const schemas = {
+  heading: {
+    label: 'Heading',
+    fields: {
+      text:  { type: 'text',   label: 'Text', inline: true, default: 'Heading' },
+      tag:   { type: 'select', label: 'HTML tag', options: [...], default: 'h2', group: 'advanced' },
+      color: { type: 'color',  label: 'Text colour', group: 'style' },
+    },
+    component: Heading,            // the Astro component
+  },
+  container: { label: 'Container', fields: {...}, blocks: '*', component: Container },
+  gallery:   { label: 'Gallery', fields: {}, blocks: ['gallery-item'], component: Gallery },
+  'gallery-item': { label: 'Image', fields: {...}, hidden: true, component: GalleryItem },
+} satisfies Record<string, BlockSchema & { component: any }>;
+
+export const presets: Preset[] = [
+  { label: 'Hero', description: 'Full-width image with a heading and two buttons', create: () => ({ ... }) },
+];
+```
+
+Field types: `text`, `richtext`, `image`, `link`, `color`, `select`, `number`, `boolean`,
+`textarea`, `code`, `svg`. `inline: true` on `text` / `richtext` / `image` makes the field
+editable by clicking it in the preview. The schema drives the sidebar form, validation on save,
+the add-block menus and the tree labels. **Presets are the section library.**
+
+### 3. Components that mark what they render
+
+Each block component receives `{ node, edit }` and spreads two helpers onto its markup:
+
+```astro
+---
+import { nodeAttrs, fieldAttrs } from '@pirateandfox/pagestack/runtime';
+const { node, edit } = Astro.props;
+---
+<div {...nodeAttrs(edit, node)}>
+  <h2 {...fieldAttrs(edit, 'text', 'text')} set:html={node.settings.text} />
+</div>
+```
+
+`edit` is `undefined` on the public site, so nothing leaks into the static output. A container
+passes `child(edit, i)` to each child. The `renderer` component takes `{ page, editing }` and
+renders the page inside the site's normal layout.
+
+## Editing
+
+Coming from the WordPress block editor:
+
+| WordPress | PageStack |
+|---|---|
+| Pages list | `/edit`: search, status, add, copy, delete |
+| Block inserter, Patterns | `+` or `/`: searchable blocks by category, Patterns tab, `+` between sections |
+| List View | Same, with drag to reorder and to move between containers |
+| Block toolbar, ⋮ menu | Move, parent, add, duplicate, delete, copy, save as pattern |
+| Settings sidebar, Page / Block tabs | Same, generated from the schema |
+| Rich text toolbar, links | Same; `⌘B`, `⌘I`, `⌘K`, and an HTML view |
+| Save draft, Publish, Preview | Same; Preview opens the unsaved draft in a new tab |
+| Revisions | The page's git history |
+| Permalink | Change URL, which also adds a redirect |
+| Menus, site options | Global content, at `/edit/global/<id>` |
+| Patterns, synced patterns | Saved patterns; synced ones update every copy in one commit |
+| Block transforms | ⋮ → Turn into… |
+| `/` in an empty block | Same |
+| Posts | `/edit/collection/<id>`: details form, Markdown with live preview |
+| Media Library | `/edit/media` |
+| Users, roles | `/edit/users`: Admin and Editor |
+
+- **Preview**: the page renders in a frame at real device widths, scaled to fit. Every change POSTs
+  the draft to `/edit/preview/<slug>`; the server renders it and only changed sections are swapped.
+- **Inline**: click text to edit it in place; click an image to open the picker (alt text required).
+- **Drafts** are kept in `localStorage` until saved; undo/redo is per session.
+- **Save** sanitises rich text, validates the document, and writes the file (local) or commits
+  (github). A hash of what you loaded is sent along; if someone saved first you get a 409 and a
+  reload prompt.
+
+Optional exports from the `sections` module:
+
+```ts
+// Fields on the Page tab, stored in page.layout
+export const pageFields = {
+  footer: { type: 'select', label: 'Footer', options: [{ value: 'big', label: 'Big' }, { value: 'small', label: 'Small' }] },
+};
+
+// Starting points offered by Add page
+export const templates = [{ label: 'Standard page', create: ({ title }) => ({ title, sections: [/* … */] }) }];
+
+// JSON files edited at /edit/global/<id>
+// Markdown folders edited at /edit/collection/<id>
+export const collections = {
+  blog: {
+    label: 'Posts', singular: 'post', dir: 'src/content/blog', url: (slug) => `/${slug}/`,
+    fields: { title: { type: 'text', label: 'Title' }, draft: { type: 'boolean', label: 'Draft' }, date: { type: 'date', label: 'Date' }, tags: { type: 'tags', label: 'Tags' } },
+  },
+};
+
+export const globals = {
+  menus: {
+    label: 'Menus',
+    file: 'src/data/menus.json',
+    fields: {
+      nav: { type: 'list', label: 'Main menu', itemLabel: 'label', fields: { label: { type: 'text', label: 'Label' } } },
+    },
+  },
+};
+```
+
+Blocks can set `category` and `keywords` for the inserter. A `list` field is a repeatable group of
+`fields`, with `itemLabel` naming the field that titles each row.
+
+## Security
+
+Everything an editor sends is treated as untrusted. On save, every field is cleaned by its type,
+and anything outside the schema is cleaned as HTML, so components can render fields with
+`set:html`. Only admins can put raw HTML in a `code` field. Uploads are checked by their bytes and
+SVGs are sanitised. Set `EDITOR_ORIGIN` to the public https origin in production.
+
+With `auth: "none-behind-proxy"`, set `EDITOR_PROXY_SECRET` if the app can be reached without going
+through the proxy: requests must then carry the same value in `x-editor-proxy-secret`. Otherwise the
+identity headers could be forged by anyone who reaches the app directly.
+
+The login rate limit is held in memory per server instance, so on Workers it slows guessing rather
+than setting a hard limit. Passkeys are what actually stops guessing.
+
+## Storage
+
+| `storage` | Reads | Saves | Uploads |
+|---|---|---|---|
+| `local` (dev default) | working tree | writes the JSON file (you commit) | written to `public/images/uploads/` |
+| `github` (build default) | Contents API on `github.branch` | one commit via the Git Data API: blobs → tree → commit → ref; with `pullRequest: true` a new `site-editor/<timestamp>-<sha>` branch + PR instead | wait on a `pagestack-uploads` branch, shown to signed-in editors, until the next save brings them along |
+
+The GitHub token (`GITHUB_TOKEN` or `EDITOR_GITHUB_TOKEN`) is read from the environment on the
+server only. A fine-grained token with *Contents: write* (and *Pull requests: write* for PR mode)
+on the one repo is enough. The host that runs the editor rebuilds and deploys from the commit
+like any other push.
+
+## Login
+
+### `auth: "passkey"` (default)
+
+- `editor-users.json` (committed, path configurable with `usersFile`) holds users and the
+  **public keys** of their passkeys. Nothing in it is secret.
+- `EDITOR_SECRET` (≥ 16 chars, environment only) signs three kinds of short-lived tokens:
+  WebAuthn challenges (5 min), the session cookie (`ase_session`, HttpOnly, SameSite=Lax, 12 h) and
+  invite links (3 days). Tokens are `base64url(json).base64url(hmac-sha256)` with the expiry inside,
+  so there is no server state.
+- **Invites** are single-use: the invite id is recorded on the credential it created. Make the first
+  one from the CLI, later ones from the "Invite another editor" panel on `/edit`:
+
+  ```bash
+  EDITOR_SECRET=… npx pagestack-invite --name "Jane Doe" --email jane@example.com --origin https://example.com
+  ```
+- `/edit/enroll?invite=…` creates the passkey (Touch ID / Face ID / Windows Hello / security key);
+  `/edit/login` signs in with it. Several passkeys per person are fine (enrol again with a new invite).
+- Set `EDITOR_ORIGIN` when a proxy rewrites `Host`; WebAuthn binds credentials to the origin the
+  browser sees.
+- The signature counter is not persisted (it would mean a commit per login; synced passkeys report 0).
+
+### `auth: "none-behind-proxy"`
+
+Use when something in front of the editor already authenticates people, e.g. **Cloudflare Access**:
+put the editor host behind an Access application for `/edit/*` and `/api/editor/*`, allow the
+client's email addresses, and the editor trusts the proxy. It reads the identity from
+`Cf-Access-Authenticated-User-Email` (or `X-Forwarded-User`) for commit attribution. This is a
+good fit when the site already sits on Cloudflare and the client prefers email one-time codes over
+passkeys. (A production deployment should also verify the Access JWT on the editor host; that's not
+implemented here.)
+
+### `auth: "none"`
+
+Dev only. A build with `auth: "none"` is refused.
+
+## Deploying the editor
+
+Requires Node 22.23.4+ and Astro 7.2.1+. On Cloudflare, add `@astrojs/cloudflare` as the host's
+adapter and set `EDITOR_SECRET`, `EDITOR_ORIGIN` and `GITHUB_TOKEN` as secrets.
+
+The editor server is a normal `@astrojs/node` standalone build. Run `node dist/server/entry.mjs`
+on any small Node host (Fly, Railway, a VPS…) with `EDITOR_SECRET`, `GITHUB_TOKEN` and
+`EDITOR_ORIGIN` set, behind HTTPS. It serves the editor routes and the static pages it was built
+with; the public site is still deployed separately from the same repo as static files. Every
+editor response is `noindex` and `no-store`.
+
+## Options
+
+| option | default | |
+|---|---|---|
+| `renderer` | required | Astro component rendering `{ page, editing }` |
+| `sections` | required | module exporting `{ schemas, presets }` |
+| `pagesDir` | `src/content/pages` | |
+| `imagesDir` / `uploadsDir` / `publicDir` | `public/images` / `public/images/uploads` / `public` | |
+| `usersFile` | `editor-users.json` | |
+| `auth` | `passkey` | `passkey` \| `none-behind-proxy` \| `none` |
+| `storage` | `local` in dev, `github` in build | |
+| `github` | — | `{ repo, branch, pullRequest }` |
+| `enabled` | dev, or `EDITOR=1` | |
+| `siteName`, `secretEnv` | `Site editor`, `EDITOR_SECRET` | |
+| `reservedSlugs` | `[]` | URLs Add page must refuse, on top of the editor's own and `src/pages` |
+| `redirectsFile` | `public/_redirects` | Change URL appends here, only if the file exists |
+| `patternsFile` | `src/content/pagestack-patterns.json` | where saved patterns live |
+| `clientIpHeader` | none | header with the client IP behind a proxy, for login rate limits, e.g. `cf-connecting-ip` |
+
+## Open-source pieces used
+
+- [SortableJS](https://github.com/SortableJS/Sortable) (MIT) for the tree drag-and-drop.
+- [@simplewebauthn/server + browser](https://simplewebauthn.dev) (MIT) for WebAuthn.
+- [@astrojs/node](https://docs.astro.build/en/guides/integrations-guide/node/) (MIT) as the editor's adapter.
+- [Puck](https://puckeditor.com) was used as a design reference for JSON page editing only; no code.
+
+MIT.

package/bin/invite.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Create the first invite link without a running editor (later invites are made at /edit/users; CLI invites create admins).
+//
+//   EDITOR_SECRET=… node packages/pagestack/bin/invite.mjs --name "Jane Doe" --email jane@example.com --origin https://example.com [--days 3]
+//
+// Same token format as src/core/auth.ts (HMAC-SHA256, base64url(json).base64url(mac)) so the
+// running site can verify it. Plain JS so it runs on any Node without a TypeScript step.
+import { createHmac, randomBytes } from 'node:crypto';
+
+const args = Object.fromEntries(process.argv.slice(2).map((a, i, all) => a.startsWith('--') ? [a.slice(2), all[i + 1]?.startsWith('--') || all[i + 1] === undefined ? 'true' : all[i + 1]] : []).filter((p) => p.length));
+const secret = process.env[args.secretEnv || 'EDITOR_SECRET'] || '';
+const { name, email, origin, days = '3' } = args;
+if (!name || !email || !origin || args.help) {
+  console.error('usage: EDITOR_SECRET=… invite.mjs --name "Jane Doe" --email jane@example.com --origin https://example.com [--days 3]');
+  process.exit(args.help ? 0 : 2);
+}
+if (secret.length < 16) { console.error('EDITOR_SECRET must be set in the environment (>= 16 characters)'); process.exit(2); }
+
+const b64url = (buf) => Buffer.from(buf).toString('base64url');
+const ttl = Math.round(Number(days) * 86400);
+const payload = { kind: 'invite', id: b64url(randomBytes(12)), name: name.trim(), email: email.trim().toLowerCase() };
+const body = b64url(Buffer.from(JSON.stringify({ payload, exp: Math.floor(Date.now() / 1000) + ttl })));
+const mac = b64url(createHmac('sha256', secret).update(body).digest());
+const token = `${body}.${mac}`;
+console.log(`${origin.replace(/\/$/, '')}/edit/enroll?invite=${encodeURIComponent(token)}`);
+console.error(`invite for ${payload.name} <${payload.email}>, valid ${days} day(s), single use`);

package/index.mjs

@@ -0,0 +1,159 @@
+// pagestack — a git-only visual section editor that ships inside an Astro site.
+//
+//   import pagestack from '@pirateandfox/pagestack';
+//   integrations: [sectionEditor({ renderer: './src/components/SectionPage.astro', sections: './src/sections/index.ts' })]
+//
+// The public site stays fully static. The editor (/edit/*, /api/editor/*) is on-demand rendered
+// and only exists when the integration is enabled: always in `astro dev`, and in `astro build`
+// when EDITOR=1 (which produces a Node server build with @astrojs/node).
+import node from '@astrojs/node';
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const VIRTUAL = 'virtual:pagestack/site';
+const VIRTUAL_RENDERER = 'virtual:pagestack/renderer';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const route = (file) => new URL(`./src/routes/${file}`, import.meta.url);
+
+/**
+ * @typedef {object} SectionEditorOptions
+ * @property {string} renderer   Astro component rendering a page: props { page, editing }.
+ * @property {string} sections   Module exporting { schemas, presets } (see runtime.ts types).
+ * @property {string} [pagesDir='src/content/pages']  Directory of <slug>.json pages.
+ * @property {string} [imagesDir='public/images']     Browsable image library root.
+ * @property {string} [uploadsDir='public/images/uploads']  Where uploads are written.
+ * @property {string} [publicDir='public']            Prefix stripped to turn file paths into URLs.
+ * @property {string} [usersFile='editor-users.json'] Passkey users (public keys only).
+ * @property {'none'|'passkey'|'none-behind-proxy'} [auth='passkey']
+ * @property {'local'|'github'} [storage]  Defaults: local in dev, github in a build.
+ * @property {{repo: string, branch?: string, pullRequest?: boolean}} [github]
+ * @property {boolean} [enabled]  Default: dev, or EDITOR=1.
+ * @property {string} [siteName]  Shown in the editor chrome.
+ * @property {string} [interactiveSelector='summary']  Elements in the preview that keep their own click
+ *                        behaviour (accordion summaries, tab titles, load-map buttons…). Everything else is
+ *                        intercepted so links don't navigate while editing.
+ * @property {string} [secretEnv='EDITOR_SECRET']  Name of the env var holding the signing secret.
+ * @property {string[]} [reservedSlugs]  Top-level URLs new pages may not take, beyond the host's own files in
+ *                        src/pages, which are found automatically. For dynamic routes such as blog posts.
+ * @property {string} [redirectsFile='public/_redirects']  When this file exists, moving a page appends a 301 to it.
+ * @property {string} [clientIpHeader]  Header holding the client IP behind a proxy, for login rate limits (e.g. cf-connecting-ip).
+ * @property {string} [patternsFile='src/content/pagestack-patterns.json']  Where saved patterns are kept.
+ *
+ * Runtime environment (never in the repo):
+ *   EDITOR_SECRET        >= 16 chars; signs sessions, WebAuthn challenges and invite links.
+ *   EDITOR_ORIGIN        Public origin (https://example.com) when the server sits behind a proxy
+ *                        that rewrites Host — passkeys are bound to the origin the browser sees.
+ *   GITHUB_TOKEN         Fine-grained token with contents (+ pull requests) on the repo, github storage only.
+ */
+
+/** Top-level URLs taken by the host's own route files (dynamic ones can't be known here). */
+function staticRoutes(srcDir) {
+  try {
+    return fs.readdirSync(path.join(srcDir, 'pages'), { withFileTypes: true })
+      .filter((e) => !/^[[_.]/.test(e.name) && e.name !== 'index.astro' && (e.isDirectory() || /\.(astro|md|mdx|html|js|ts)$/.test(e.name)))
+      .map((e) => e.name.replace(/\.[^.]+$/, ''));
+  } catch { return []; }
+}
+
+/** @param {SectionEditorOptions} userOptions */
+export default function sectionEditor(userOptions) {
+  if (!userOptions?.renderer || !userOptions?.sections) throw new Error('pagestack: `renderer` and `sections` are required');
+  // When the site has no adapter of its own we bring @astrojs/node along and forward every
+  // integration hook to it (an integration added via updateConfig() doesn't get to call
+  // setAdapter() in time, so we proxy its hooks instead).
+  let adapter = null;
+  const forward = (hook) => async (params) => { if (adapter?.hooks?.[hook]) await adapter.hooks[hook](params); };
+  const forwarded = Object.fromEntries(['astro:config:done', 'astro:server:setup', 'astro:server:start', 'astro:server:done', 'astro:build:start', 'astro:build:setup', 'astro:build:ssr', 'astro:build:generated', 'astro:build:done'].map((h) => [h, forward(h)]));
+  return {
+    name: 'pagestack',
+    hooks: {
+      ...forwarded,
+      'astro:config:setup': async (params) => {
+        const { config, command, injectRoute, updateConfig, addMiddleware, logger } = params;
+        const enabled = userOptions.enabled ?? (command === 'dev' || process.env.EDITOR === '1');
+        if (!enabled) { logger.info('disabled (static build). Set EDITOR=1 to build the editor.'); return; }
+        const isBuild = command === 'build';
+        const options = {
+          pagesDir: 'src/content/pages',
+          imagesDir: 'public/images',
+          uploadsDir: 'public/images/uploads',
+          publicDir: 'public',
+          usersFile: 'editor-users.json',
+          auth: 'passkey',
+          storage: isBuild ? 'github' : 'local',
+          siteName: 'Site editor',
+          secretEnv: 'EDITOR_SECRET',
+          interactiveSelector: 'summary',
+          redirectsFile: 'public/_redirects',
+          patternsFile: 'src/content/pagestack-patterns.json',
+          ...userOptions,
+          github: userOptions.github ?? null,
+        };
+        if (isBuild && options.auth === 'none') {
+          throw new Error('pagestack: auth: "none" is only allowed in `astro dev`. Use "passkey" or "none-behind-proxy" for a build.');
+        }
+        if (options.storage === 'github' && !options.github?.repo) {
+          throw new Error('pagestack: storage "github" needs github.repo ("owner/name")');
+        }
+        const root = fileURLToPath(config.root);
+        const abs = (p) => path.isAbsolute(p) ? p : path.resolve(root, p);
+        const reservedSlugs = [...new Set([...(options.reservedSlugs ?? []), ...staticRoutes(fileURLToPath(config.srcDir))])];
+        const serial = { ...options, reservedSlugs, root, renderer: abs(options.renderer), sections: abs(options.sections), command };
+
+        updateConfig({
+          vite: {
+            plugins: [{
+              name: 'pagestack:virtual',
+              resolveId(id) { if (id === VIRTUAL || id === VIRTUAL_RENDERER) return '\0' + id; },
+              load(id) {
+                // The renderer (and the site layout/CSS behind it) is only imported by the preview
+                // route, so the editor shell doesn't drag the whole site's CSS into its page.
+                if (id === '\0' + VIRTUAL_RENDERER) return `export { default as Renderer } from ${JSON.stringify(serial.renderer)};`;
+                if (id !== '\0' + VIRTUAL) return;
+                return [
+                  `export * as site from ${JSON.stringify(serial.sections)};`,
+                  `export const options = ${JSON.stringify(serial)};`,
+                ].join('\n');
+              },
+            }],
+            // The package is consumed from source (.ts/.astro); make sure Vite transforms it.
+            ssr: { noExternal: ['@pirateandfox/pagestack'] },
+            // Pre-bundle the editor's browser deps so dev doesn't re-optimise (and reload) mid-session.
+            optimizeDeps: { include: ['sortablejs', '@simplewebauthn/browser', 'marked'] },
+          },
+        });
+        if (!config.adapter) {
+          adapter = node({ mode: 'standalone' });
+          await adapter.hooks['astro:config:setup']?.(params);
+          // Astro's build checks `config.adapter`; integrations added this late aren't hooked
+          // up automatically, hence the forwarded hooks above.
+          updateConfig({ adapter });
+        }
+
+        addMiddleware({ order: 'pre', entrypoint: new URL('./src/server/middleware.ts', import.meta.url) });
+
+        injectRoute({ pattern: '/edit', entrypoint: route('edit-index.astro'), prerender: false });
+        injectRoute({ pattern: '/edit/login', entrypoint: route('login.astro'), prerender: false });
+        injectRoute({ pattern: '/edit/enroll', entrypoint: route('enroll.astro'), prerender: false });
+        injectRoute({ pattern: '/edit/preview/[...slug]', entrypoint: route('preview.astro'), prerender: false });
+        injectRoute({ pattern: '/edit/global/[id]', entrypoint: route('edit-global.astro'), prerender: false });
+        injectRoute({ pattern: '/edit/collection/[id]', entrypoint: route('edit-collection.astro'), prerender: false });
+        injectRoute({ pattern: '/edit/collection/[id]/[...slug]', entrypoint: route('edit-item.astro'), prerender: false });
+        injectRoute({ pattern: '/edit/media', entrypoint: route('edit-media.astro'), prerender: false });
+        injectRoute({ pattern: '/edit/users', entrypoint: route('edit-users.astro'), prerender: false });
+        injectRoute({ pattern: '/edit/[...slug]', entrypoint: route('edit-page.astro'), prerender: false });
+        injectRoute({ pattern: '/api/editor/pages', entrypoint: route('api/pages.ts'), prerender: false });
+        injectRoute({ pattern: '/api/editor/page/[...slug]', entrypoint: route('api/page.ts'), prerender: false });
+        injectRoute({ pattern: '/api/editor/patterns', entrypoint: route('api/patterns.ts'), prerender: false });
+        injectRoute({ pattern: '/api/editor/global/[id]', entrypoint: route('api/global.ts'), prerender: false });
+        injectRoute({ pattern: '/api/editor/images', entrypoint: route('api/images.ts'), prerender: false });
+        injectRoute({ pattern: '/api/editor/collection/[id]/[...slug]', entrypoint: route('api/collection.ts'), prerender: false });
+        injectRoute({ pattern: '/api/editor/users', entrypoint: route('api/users.ts'), prerender: false });
+        injectRoute({ pattern: '/api/editor/asset/[...path]', entrypoint: route('api/asset.ts'), prerender: false });
+        injectRoute({ pattern: '/api/editor/auth/[action]', entrypoint: route('api/auth.ts'), prerender: false });
+        logger.info(`enabled — storage: ${options.storage}, auth: ${options.auth}. Open /edit`);
+      },
+    },
+  };
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@pirateandfox/pagestack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.5",
+  "description": "PageStack: visual section editor for Astro sites. Git-only, static public site, passkey login, saves are commits.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "pagestack-invite": "bin/invite.mjs"
+  },
+  "exports": {
+    ".": "./index.mjs",
+    "./runtime": "./src/runtime.ts",
+    "./core/*": "./src/core/*.ts"
+  },
+  "files": [
+    "index.mjs",
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "astro": ">=7.2.1"
+  },
+  "dependencies": {
+    "@astrojs/node": "11.1.11",
+    "@simplewebauthn/browser": "^13.0.0",
+    "@simplewebauthn/server": "^13.0.0",
+    "marked": "^18.1.3",
+    "sortablejs": "^1.15.7",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/sortablejs": "^1.15.8",
+    "happy-dom": "^21.0.4",
+    "vitest": "^4.0.0"
+  },
+  "keywords": [
+    "astro-integration",
+    "astro-component",
+    "withastro",
+    "visual-editor",
+    "cms",
+    "git-based-cms",
+    "sections"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pirateandfox/pagestack.git"
+  },
+  "homepage": "https://github.com/pirateandfox/pagestack#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.23.4"
+  }
+}

package/src/client/auth.ts

@@ -0,0 +1,35 @@
+// Browser side of passkey login / enrolment (login.astro, enroll.astro).
+import { browserSupportsWebAuthn, startAuthentication, startRegistration } from '@simplewebauthn/browser';
+
+const root = document.querySelector<HTMLElement>('[data-ase-auth]')!;
+const go = document.getElementById('ase-auth-go') as HTMLButtonElement | null;
+const errEl = document.getElementById('ase-auth-error')!;
+const fail = (msg: string) => { errEl.textContent = msg; errEl.hidden = false; if (go) go.disabled = false; };
+const post = async (action: string, body: unknown) => {
+  const res = await fetch(`/api/editor/auth/${action}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data.error || `${action} failed (${res.status})`);
+  return data;
+};
+
+if (!browserSupportsWebAuthn()) fail('This browser does not support passkeys.');
+else if (go) go.addEventListener('click', async () => {
+  go.disabled = true; errEl.hidden = true;
+  try {
+    if (root.dataset.aseAuth === 'login') {
+      const { options, token } = await post('login-options', {});
+      const response = await startAuthentication({ optionsJSON: options });
+      const { next } = await post('login-verify', { token, response, next: root.dataset.next });
+      location.assign(next || '/edit');
+    } else {
+      const { options, token } = await post('register-options', { invite: root.dataset.invite });
+      const response = await startRegistration({ optionsJSON: options });
+      const label = (document.getElementById('ase-auth-label') as HTMLInputElement | null)?.value;
+      await post('register-verify', { token, response, label });
+      location.assign('/edit');
+    }
+  } catch (e: any) {
+    fail(e?.name === 'NotAllowedError' ? 'Cancelled, or no passkey was offered. Try again.' : e?.message || String(e));
+  }
+});
+root.dataset.ready = '1'; // tests wait for this before clicking

package/src/client/collection.ts

@@ -0,0 +1,37 @@
+// The list of a collection: add, delete, search.
+import { slugify, uniqueSlug } from '../core/pages';
+import { confirmDialog, promptDialog, toast } from './ui';
+
+const boot = (window as any).__ASE_COLLECTION__ as { id: string; singular: string; slugs: string[]; reserved: string[] };
+const api = `/api/editor/collection/${boot.id}`;
+
+document.getElementById('ase-add-item')!.addEventListener('click', async () => {
+  const title = await promptDialog({ title: `Add ${boot.singular}`, label: 'Title', submit: `Add ${boot.singular}` });
+  if (!title) return;
+  const slug = uniqueSlug(slugify(title) || boot.singular, [...boot.slugs, ...boot.reserved]);
+  const res = await fetch(api, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ title, slug }) });
+  const data = await res.json();
+  if (!res.ok) { toast(data.error || 'That did not work.', 'error'); return; }
+  location.href = `/edit/collection/${boot.id}/${data.slug}`;
+});
+
+document.getElementById('ase-pagelist')!.addEventListener('click', async (e) => {
+  const b = (e.target as HTMLElement).closest<HTMLElement>('[data-delete]');
+  if (!b) return;
+  const row = b.closest('li')!;
+  const name = row.querySelector('strong')!.textContent;
+  if (!await confirmDialog(`Delete ${boot.singular}`, `Delete "${name}"? It stays in the site's git history, so it can be recovered by a developer.`, 'Delete', 'danger')) return;
+  const res = await fetch(`${api}/${b.dataset.delete}`, { method: 'DELETE' });
+  const data = await res.json();
+  if (!res.ok) { toast(data.error || 'Delete failed', 'error'); return; }
+  row.remove();
+  toast(`Deleted ${name}.`, 'ok');
+});
+
+const search = document.getElementById('ase-page-search') as HTMLInputElement;
+search.addEventListener('input', () => {
+  const q = search.value.trim().toLowerCase();
+  let shown = 0;
+  document.querySelectorAll<HTMLElement>('#ase-pagelist > li').forEach((li) => { const on = li.dataset.search!.includes(q); li.hidden = !on; if (on) shown++; });
+  document.getElementById('ase-no-match')!.hidden = shown > 0;
+});