@makerclay/core 1.0.0

package/src/collections/routes.js

@@ -0,0 +1,166 @@
+import express from 'express';
+import { can } from '../auth/can.js';
+import { jsonError } from '../json-errors.js';
+import { createRateLimiter, parseRate } from '../auth/rate-limit.js';
+
+// The collection HTTP surface.
+//
+// The submit lane is deliberately the odd one out: CORS-open, CSRF-exempt, and
+// authenticated by a token in the BODY rather than by a cookie. That is not a
+// gap, it is the feature — a plain <form> on the owner's blog posting into their
+// makerclay is the thing collections exist for, and a cookie-based defense
+// cannot survive that trip.
+//
+// Everything else on this router is owner-only or code-gated.
+
+const READ_CODE_HEADER = 'x-collection-code';
+
+export function mountCollectionRoutes(ctx) {
+  const { router, config, collections, gateCtx, wrap, clock } = ctx;
+  const json = express.json({ limit: '1mb' });
+  const rate = parseRate(config.collections?.submitRateLimit, { max: 30, windowMs: 60_000 });
+  const submitLimiter = createRateLimiter({ clock, ...rate });
+
+  function requireOwner(req, res, next) {
+    if (!can(req.actor, 'admin', null, gateCtx)) return jsonError(res, 'not-found', 'Not found');
+    return next();
+  }
+
+  function openCors(res) {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Vary', 'Origin');
+    res.setHeader('Access-Control-Allow-Headers', `Content-Type, ${READ_CODE_HEADER}`);
+    // Never Allow-Credentials: the token in the body is the credential, and an
+    // open origin plus cookies is how a same-origin attacker gets a free ride.
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+  }
+
+  function collectionOf(req) {
+    return collections.bySlug(req.params.slug);
+  }
+
+  // ---- marking (owner) ---------------------------------------------------
+
+  router.post('/collection', requireOwner, json, wrap(async (req, res) => {
+    const relPath = String(req.body?.path || '').replace(/^\/+/, '');
+    if (!relPath) return jsonError(res, 'bad-request', 'path is required.');
+    const collection = await collections.mark({ actor: req.actor, relPath, ctx: gateCtx });
+    return res.json({
+      ok: true,
+      slug: collection.slug,
+      submitToken: collection.submitToken,
+      accepting: collection.accepting,
+      submitUrl: `/_/collection/${collection.slug}/records`,
+    });
+  }));
+
+  router.post('/collection/unmark', requireOwner, json, wrap(async (req, res) => {
+    const relPath = String(req.body?.path || '').replace(/^\/+/, '');
+    if (!relPath) return jsonError(res, 'bad-request', 'path is required.');
+    return res.json(await collections.unmark({ actor: req.actor, relPath, ctx: gateCtx }));
+  }));
+
+  router.post('/collection/:slug/accepting', requireOwner, json, wrap(async (req, res) => {
+    const updated = collections.setAccepting({
+      actor: req.actor, collection: collectionOf(req), ctx: gateCtx, accepting: !!req.body?.accepting,
+    });
+    return res.json({ ok: true, accepting: updated.accepting });
+  }));
+
+  // ---- records -----------------------------------------------------------
+
+  router.options(/^\/collection\/[^/]+\/records(\/.*)?$/, (req, res) => {
+    openCors(res);
+    res.status(204).end();
+  });
+
+  router.get('/collection/:slug/records', requireOwner, wrap(async (req, res) => {
+    const collection = collectionOf(req);
+    const records = await collections.list({ actor: req.actor, collection, ctx: gateCtx });
+    return res.json({
+      ok: true, slug: collection.slug, accepting: !!collection.accepting, count: records.length, records,
+    });
+  }));
+
+  // The public lane.
+  router.post('/collection/:slug/records', json, wrap(async (req, res) => {
+    openCors(res);
+    const collection = collectionOf(req);
+    const isOwner = collections.isOwnerOf(req.actor, collection, gateCtx);
+    if (!isOwner) {
+      const limit = submitLimiter.check(req);
+      if (!limit.ok) {
+        res.setHeader('Retry-After', String(limit.retryAfter));
+        return jsonError(res, 'rate-limited', 'Too many submissions. Slow down.');
+      }
+    }
+
+    const body = req.body || {};
+    const result = await collections.submit({
+      collection,
+      actor: req.actor,
+      ctx: gateCtx,
+      key: body.key ?? null,
+      data: body.data && typeof body.data === 'object' ? body.data : body,
+      code: typeof body.code === 'string' ? body.code : null,
+      submitToken: typeof body.token === 'string' ? body.token : null,
+    });
+
+    return res.status(result.created ? 201 : 200).json({
+      ok: true,
+      key: result.key,
+      opaque: result.record.opaque,
+      created: result.created,
+    });
+  }));
+
+  router.get('/collection/:slug/records/:key', wrap(async (req, res) => {
+    openCors(res);
+    const collection = collectionOf(req);
+    const record = await collections.read({
+      collection,
+      actor: req.actor,
+      ctx: gateCtx,
+      key: req.params.key,
+      code: req.get(READ_CODE_HEADER) || null,
+      req,
+      res,
+    });
+    if (!record) return jsonError(res, 'not-found', 'No such record.');
+    return res.json({ ok: true, record });
+  }));
+
+  router.put('/collection/:slug/records/:key', json, wrap(async (req, res) => {
+    openCors(res);
+    const collection = collectionOf(req);
+    const body = req.body || {};
+    const record = await collections.update({
+      collection,
+      actor: req.actor,
+      ctx: gateCtx,
+      key: req.params.key,
+      // The WRITE code travels in the body, the read code in a header. Different
+      // lanes, so a read-only viewer never learns the write code from a URL or
+      // a proxy log.
+      code: typeof body.code === 'string' ? body.code : null,
+      data: body.data && typeof body.data === 'object' ? body.data : body,
+      req,
+      res,
+    });
+    return res.json({ ok: true, record });
+  }));
+
+  router.delete('/collection/:slug/records/:key', requireOwner, wrap(async (req, res) => {
+    const collection = collectionOf(req);
+    return res.json(await collections.remove({
+      actor: req.actor, collection, ctx: gateCtx, key: req.params.key,
+    }));
+  }));
+
+  router.post('/collection/:slug/records/:key/restore', requireOwner, wrap(async (req, res) => {
+    const collection = collectionOf(req);
+    return res.json(await collections.restore({
+      actor: req.actor, collection, ctx: gateCtx, key: req.params.key,
+    }));
+  }));
+}

package/src/create-host.js

@@ -0,0 +1,351 @@
+import express from 'express';
+import { EventEmitter } from 'node:events';
+
+import { createPaths } from './paths.js';
+import { createLockPool } from './util/locks.js';
+import { acquireLock } from './util/lockfile.js';
+import { cookieMiddleware } from './util/cookies.js';
+import { createRequestResolution } from './requests.js';
+import { mountUploadRoutes } from './routes/upload.js';
+import { mountSyncRoutes } from './routes/sync.js';
+import { mountMetaRoutes } from './routes/meta.js';
+import { mountSaveRoutes } from './routes/save.js';
+import { mountReadRoutes, mountDocumentLane } from './routes/read.js';
+import { wrap } from './util/express.js';
+import { ulid, token as mintToken } from './util/id.js';
+import { createNodes } from './nodes/store.js';
+import { createVersions } from './versions/index.js';
+import { createReplace } from './documents/replace.js';
+import { createServe } from './documents/serve.js';
+import { createDerived } from './derived/index.js';
+import { createLiveSync } from './livesync.js';
+import { none } from './auth/none.js';
+import { jsonErrorHandler, jsonError } from './json-errors.js';
+import { hostMeta } from './spec/meta.js';
+import { mountVersionRoutes } from './versions/routes.js';
+import { createSaveTokens } from './share/save-tokens.js';
+import { createIsolation } from './tenants/isolation.js';
+import { mountTokenLanes } from './auth/token-lanes.js';
+import { createOps } from './nodes/ops.js';
+import { createScanner } from './nodes/scanner.js';
+import { createListing } from './admin/listing.js';
+import { createTemplates } from './templates.js';
+import { createRecovery } from './recovery.js';
+import { mountBoot } from './boot.js';
+import { createAttic } from './attic.js';
+import { mountAdminRoutes } from './admin/routes.js';
+import { createUi } from './ui.js';
+import { mountClientRoutes } from './client.js';
+import { mountPageRoutes } from './pages.js';
+import { createShares, mountShareRoutes } from './share/index.js';
+import { createCollections } from './collections/index.js';
+import { mountCollectionRoutes } from './collections/routes.js';
+import { createTenants, TENANT_DEFAULTS } from './tenants/index.js';
+import { mountTenantRoutes } from './tenants/routes.js';
+
+// One defaults tree, exported, because there used to be two: this one and a
+// second in packages/makerclay/src/config.js, bridged by a `toHostOptions` that
+// hardcoded most of `features` to true. The consequence was not cosmetic. Every
+// flag it hardcoded was unreachable from config.json, so a person could not turn
+// off the dashboard, the editor, uploads, collections, share links or the data
+// API however they edited that file.
+//
+// Two kinds of setting live here and the difference is worth keeping straight:
+//
+//   PRODUCT switches   isolation, requireAuthToRead, capabilities, limits,
+//                      versions, features, tenants, collections. Things a person
+//                      running the server decides, so config.json reaches all of
+//                      them and `makerclay` writes them into the file it creates.
+//
+//   EMBEDDER switches  layout, scan, plus the constructor-only arguments (data,
+//                      store, auth, clock, ids, logger, hostId, publicUrl). These
+//                      are for whoever CALLS createHost. `scan` in particular is
+//                      a test and desktop concern, not a setting to hand a person.
+//
+// `features.tenants` is THE tenant switch; the `tenants` object holds only knobs.
+// See tenants/index.js, which had to say the same thing about a second spelling.
+export const HOST_DEFAULTS = {
+  isolation: 'untrusted',
+  layout: 'clean',
+  requireAuthToRead: false,
+  capabilities: { conditional: true, sync: true, format: true, upload: true },
+  limits: { saveBytes: 20e6, uploadBytes: 50e6, maxFolderDepth: 5, sseKeepaliveMs: 30_000 },
+  versions: { driver: 'files', maxAgeDays: 60, keepNewest: 20 },
+  features: {
+    dashboard: true, editor: true, uploads: true, collections: true,
+    share: true, tenants: false, tailwind: false, dataApi: true,
+  },
+  collections: { maxRecords: 10_000, submitRateLimit: '30/min' },
+  scan: { boot: true, watch: true },
+  tenants: TENANT_DEFAULTS,
+};
+
+const DEFAULTS = HOST_DEFAULTS;
+
+function mergeConfig(options) {
+  return {
+    ...DEFAULTS,
+    ...options,
+    capabilities: { ...DEFAULTS.capabilities, ...(options.capabilities || {}) },
+    limits: { ...DEFAULTS.limits, ...(options.limits || {}) },
+    versions: { ...DEFAULTS.versions, ...(options.versions || {}) },
+    features: { ...DEFAULTS.features, ...(options.features || {}) },
+    collections: { ...DEFAULTS.collections, ...(options.collections || {}) },
+    scan: { ...DEFAULTS.scan, ...(options.scan || {}) },
+    tenants: { ...DEFAULTS.tenants, ...(options.tenants || {}) },
+  };
+}
+
+
+export function createHost(options = {}) {
+  const config = mergeConfig(options);
+  const logger = config.logger || console;
+  const clock = config.clock || { now: () => Date.now() };
+  const ids = config.ids || { ulid, token: mintToken };
+  const hostId = config.hostId || ulid().slice(-8);
+
+  const paths = createPaths({
+    data: config.data,
+    layout: config.layout,
+    maxFolderDepth: config.limits.maxFolderDepth,
+  });
+  const lock = acquireLock(paths.files.lock);
+
+  const store = config.store ?? null;
+  // A migration that throws is the first thing §18.3 names as a reason to be in
+  // recovery mode, so it must not take the constructor down with it. Throwing
+  // here leaves an embedder that catches it holding the data directory's lock
+  // with no host to close, and prints no recovery URL for the one person who
+  // could fix it.
+  let storeError = null;
+  if (store) {
+    try {
+      store.open({ paths, clock });
+    } catch (error) {
+      storeError = error;
+    }
+  }
+
+  const locks = createLockPool();
+  const events = new EventEmitter();
+  events.setMaxListeners(0);
+  const nodes = createNodes({ store, clock, ids });
+  const versions = createVersions({ paths, locks, config: config.versions, clock, logger });
+  const liveSync = config.capabilities.sync === false
+    ? null
+    : createLiveSync({ hostId, config, logger });
+  const derived = createDerived({ paths, config, liveSync, logger });
+  const auth = config.auth || none();
+
+  const gateCtx = {
+    requireAuthToRead: !!config.requireAuthToRead,
+  };
+
+  const isolation = createIsolation({ config, store, logger });
+  const saveTokens = createSaveTokens({ store, nodes, clock, ids });
+  const serve = createServe({
+    paths, nodes, config, isolation, saveTokens,
+  });
+  const { replace } = createReplace({
+    paths, nodes, versions, locks, events, config, clock, logger, derived,
+  });
+
+  const {
+    notFoundDocument, resolveHref, resolveTarget, resolveSaveToken,
+  } = createRequestResolution({ serve, store, clock, gateCtx });
+  const { tryResolveRead } = paths;
+
+  const ops = createOps({
+    paths, nodes, store, versions, locks, events, clock, ids, logger, replace, derived,
+  });
+  const listing = createListing({ paths, nodes, isolation, store });
+  const templates = createTemplates({ logger });
+  const ui = createUi({ paths, logger });
+  const shares = config.features.share === false
+    ? null
+    : createShares({ store, nodes, paths, clock, ids, events, logger });
+  const collections = config.features.collections === false
+    ? null
+    : createCollections({ store, nodes, paths, versions, clock, ids, events, config, logger });
+  const tenants = createTenants({
+    store, nodes, paths, ops, versions, config, clock, ids, events, logger, saveTokens,
+    // Lazily, because the auth provider mounts its routes (and builds its
+    // session store) after this module is constructed.
+    sessions: () => auth.sessions || null,
+  });
+  const scanner = createScanner({ paths, nodes, locks, events, config, clock, versions, logger });
+  const recovery = createRecovery({ paths, store, nodes, versions, clock, logger });
+  const attic = createAttic({ paths, store, nodes, versions, recovery, replace, locks, logger });
+
+  // Derived work runs after the response, so a test (or a shutdown) that stops
+  // at the response would otherwise race a sidecar write still in flight.
+  const background = new Set();
+  function track(promise) {
+    const entry = Promise.resolve(promise).catch((error) => {
+      logger.error?.('[makerclay] background work failed:', error?.message || error);
+    });
+    background.add(entry);
+    entry.finally(() => background.delete(entry));
+    return entry;
+  }
+  async function settled() {
+    while (background.size) await Promise.all([...background]);
+  }
+
+  const app = express();
+  app.disable('x-powered-by');
+  app.set('etag', false);
+
+  const booted = mountBoot({
+    app, config, paths, store, storeError, recovery, scanner, ui, logger,
+  });
+  const { ready, recoveryUi } = booted;
+
+  app.use(cookieMiddleware);
+
+  app.use(wrap(async (req, res, next) => {
+    const identified = await auth.identify(req, { store, nodes, config });
+    req.actor = identified ? { grants: {}, ...identified } : { kind: 'guest', grants: {} };
+    // Share links are capabilities, not identities: they are added to whoever
+    // the request already is, and they never change `kind`.
+    if (shares) req.actor.grants.shares = shares.grantsFor(req, res);
+    auth.decorate?.(req, res, req.actor);
+    next();
+  }));
+
+  const system = express.Router();
+
+  mountTokenLanes({ system, config });
+
+  system.get('/health', (req, res) => {
+    const { state } = booted;
+    res.json({
+      ok: state.state !== 'recover',
+      spec: hostMeta(config.capabilities).spec,
+      hostId,
+      state: state.state,
+      reason: state.reason ?? null,
+    });
+  });
+
+  mountMetaRoutes({
+    system, config, serve, gateCtx, resolveTarget, resolveSaveToken, tryResolveRead,
+  });
+
+  mountSaveRoutes({
+    system, config, nodes, serve, tenants, replace, gateCtx,
+    resolveHref, resolveSaveToken, track,
+  });
+
+  mountUploadRoutes({
+    system, config, ops, tenants, gateCtx, resolveTarget, resolveSaveToken,
+  });
+
+  mountSyncRoutes({
+    system, config, liveSync, nodes, gateCtx, resolveHref, resolveSaveToken,
+  });
+
+  mountVersionRoutes({
+    router: system, config, paths, nodes, versions, replace, resolveTarget,
+    resolveSaveToken, tryResolveRead, gateCtx, logger, track,
+    isolationFor: serve.isolationFor,
+  });
+
+  mountReadRoutes({ system, config, serve, derived, resolveTarget });
+
+  mountClientRoutes({ router: system, logger });
+
+  mountAdminRoutes({
+    router: system, config, paths, nodes, store, ops, listing, attic, templates, events,
+    gateCtx, wrap, track, clock, logger,
+  });
+
+  if (shares) {
+    mountShareRoutes({
+      router: system, config, shares, nodes, store, ui, gateCtx, wrap,
+      publicUrl: config.publicUrl || null,
+    });
+  }
+
+  if (collections) {
+    mountCollectionRoutes({
+      router: system, config, collections, nodes, store, gateCtx, wrap, clock,
+    });
+  }
+
+  if (tenants.enabled) {
+    mountTenantRoutes({
+      router: system, config, tenants, nodes, resolveTarget, gateCtx, wrap, clock, ui,
+    });
+  }
+
+  mountPageRoutes({
+    router: system, config, paths, nodes, ui, listing, versions, templates,
+    gateCtx, wrap, resolveTarget, serve, saveTokens, logger,
+  });
+
+  // Everything else under the host's own prefix is reserved, so `/_/foo.html`
+  // can never fall through to the document lane and serve a document.
+  system.use((req, res) => jsonError(res, 'not-found', 'Not found'));
+
+  auth.routes?.(app, { config, paths, store, nodes, clock, ids, logger, gateCtx, ui, sessions: null });
+  app.use('/_', system);
+
+  // No generic mount/plugin seam here, deliberately. An embedder (hyperclay-local
+  // is the one that matters) owns its own Express app and mounts `host.app`
+  // inside it, so its routes sit in FRONT of core's and their precedence is
+  // obvious. The old `config.mounts` callback ran after every reserved route was
+  // installed, so it could not cleanly override anything, which is the whole
+  // reason it was never used.
+
+  // ---- the document lane -------------------------------------------------
+  mountDocumentLane({ app, config, serve, events, resolveTarget, notFoundDocument });
+
+  app.use(jsonErrorHandler({ logger }));
+
+  const host = {
+    id: hostId,
+    app,
+    config,
+    paths,
+    store,
+    nodes,
+    versions,
+    events,
+    locks,
+    liveSync,
+    derived,
+    isolation,
+    saveTokens,
+    documents: { replace },
+    serve,
+    ops,
+    listing,
+    templates,
+    scanner,
+    recovery,
+    attic,
+    ui,
+    shares,
+    collections,
+    tenants,
+    auth,
+    recoveryUi,
+    helpers: { resolveHref, resolveTarget, tryResolveRead, resolveSaveToken, gateCtx, wrap },
+    ready,
+    get state() { return booted.state; },
+    settled,
+
+    async close() {
+      liveSync?.closeAll();
+      await ready.catch(() => {});
+      await scanner.close();
+      await settled();
+      store?.close();
+      lock.release();
+      events.removeAllListeners();
+    },
+  };
+
+  return host;
+}

package/src/derived/data-extractor.js

@@ -0,0 +1,22 @@
+import * as cheerio from 'cheerio';
+import { extract, findRulesIn, parseRelaxed } from 'hyper-html-api/engine';
+import cheerioAdapter from 'hyper-html-api/cheerio';
+
+// Thin wrapper over the shared hyper-html-api engine. The engine is pure ESM and
+// so is this core, so unlike hyperclay-local's CommonJS port there is no dynamic
+// import dance: these are plain synchronous calls.
+
+export function extractData(html, rules) {
+  return extract(cheerioAdapter, cheerio.load(html).root(), rules);
+}
+
+export function extractViaTag(html, token) {
+  const $ = cheerio.load(html);
+  const found = findRulesIn(cheerioAdapter, $.root(), token);
+  if (!found) return null;
+  return extract(cheerioAdapter, $.root(), found.rules);
+}
+
+export function parseExtractionRules(source) {
+  return parseRelaxed(source);
+}

package/src/derived/index.js

@@ -0,0 +1,121 @@
+import path from 'upath';
+import { extractViaTag } from './data-extractor.js';
+import { atomicWrite, readFileTextIfExists, statInfo, unlinkIfExists } from '../util/fsx.js';
+
+// Derived artifacts: the per-document data sidecar and the Tailwind stylesheet.
+// Everything here runs AFTER the response has been sent (§9.1 step 14), so a
+// failure is recorded for `doctor` and never converted into an HTTP failure.
+
+async function loadTailwind(logger) {
+  try {
+    return await import('tailwind-hyperclay');
+  } catch {
+    logger.warn?.('[makerclay] tailwind-hyperclay is not installed; Tailwind generation is off');
+    return null;
+  }
+}
+
+export function createDerived({ paths, config, liveSync, logger = console }) {
+  const features = config.features || {};
+  let tailwindModule = undefined;
+
+  // The sidecar records WHICH bytes it was derived from, and freshness is that
+  // identity matching, not the two files' timestamps being in the right order.
+  //
+  // Ordering cannot carry this. Nothing serializes sidecar writes: the save lane
+  // hands its derived work out past the lock, and `/_/api` rebuilds lazily on a
+  // miss, so a request that read the document before a save can finish writing
+  // its sidecar after that save wrote one. Judged by mtime that loser looks
+  // NEWER than the source it is already behind, so it passes the freshness check
+  // and keeps being served, and the next save is what finally clears it. A wrong
+  // answer that persists is worth more than the extra stat this costs.
+  //
+  // `statInfo` reports mtime in nanoseconds for this exact reason: whole
+  // milliseconds collide often enough that two writes in the same tick would
+  // compare equal.
+  function sourceIdentity(stat) {
+    return stat ? { size: stat.size, mtimeNs: String(stat.mtimeNs) } : null;
+  }
+
+  async function writeSidecar(node, html, sourcePath = null) {
+    const target = paths.derivedApiPath(node.owner, node.path.replace(/\.(html|htmlclay)$/i, ''));
+    let data = null;
+    try {
+      data = extractViaTag(html, 'api');
+    } catch (error) {
+      logger.warn?.('[makerclay] api rules extraction failed:', error?.message || error);
+      data = null;
+    }
+    if (data === null) {
+      await unlinkIfExists(target);
+      return null;
+    }
+    const source = sourceIdentity(sourcePath ? await statInfo(sourcePath) : null);
+    await atomicWrite(target, JSON.stringify({ source, data }));
+    return target;
+  }
+
+  async function readSidecar(node, sourcePath) {
+    const target = paths.derivedApiPath(node.owner, node.path.replace(/\.(html|htmlclay)$/i, ''));
+    const stored = await readFileTextIfExists(target);
+    if (stored === null) return null;
+
+    let parsed = null;
+    try {
+      parsed = JSON.parse(stored);
+    } catch {
+      return null;
+    }
+    // A sidecar with no recorded source is one this host cannot vouch for: it
+    // either predates this format or was written without a path to stat. Treat
+    // it as a miss and rebuild rather than serving bytes of unknown provenance.
+    if (!parsed || typeof parsed !== 'object' || !parsed.source) return null;
+
+    const current = sourceIdentity(await statInfo(sourcePath));
+    if (!current) return null;
+    if (current.size !== parsed.source.size || current.mtimeNs !== parsed.source.mtimeNs) return null;
+
+    return JSON.stringify(parsed.data);
+  }
+
+  async function writeTailwind(node, html) {
+    if (!features.tailwind) return null;
+    if (tailwindModule === undefined) tailwindModule = await loadTailwind(logger);
+    if (!tailwindModule) return null;
+    const name = tailwindModule.getTailwindCssName(html);
+    if (!name) return null;
+    const css = await tailwindModule.compileTailwind(html);
+    const target = paths.derivedTailwindPath(node.owner, name);
+    await atomicWrite(target, css);
+    return target;
+  }
+
+  function scopeTailwindLink(node, html) {
+    if (!features.tailwind || !tailwindModule) return html;
+    if (!tailwindModule.hasAnyTailwindLink?.(html)) return html;
+    const dir = path.dirname(node.path);
+    const sitePath = dir === '.' ? '' : dir;
+    const base = path.basename(node.path, path.extname(node.path));
+    return tailwindModule.replaceTailwindLink(html, base, sitePath);
+  }
+
+  async function onSaved({ node, html, senderId, sourcePath = null }) {
+    // Morph view-mode tabs with the persisted on-disk HTML. Edit-mode tabs are
+    // untouched: they ride the live lane through /_/sync.
+    if (liveSync) {
+      liveSync.broadcast(node.owner, node.path, { html, sender: senderId || 'server-save' }, { lane: 'saved' });
+    }
+    // The sidecar goes first, so a Tailwind failure cannot skip it and leave
+    // stale API data on disk.
+    if (features.dataApi !== false) await writeSidecar(node, html, sourcePath);
+    if (features.tailwind) {
+      try {
+        await writeTailwind(node, html);
+      } catch (error) {
+        logger.warn?.('[makerclay] tailwind compile failed (non-fatal):', error?.message || error);
+      }
+    }
+  }
+
+  return { onSaved, writeSidecar, readSidecar, writeTailwind, scopeTailwindLink };
+}