@odla-ai/chapter 0.34.0 → 0.35.0

package/README.md

@@ -432,8 +432,11 @@ The document carries the source, exact chapter/environment/Stripe-mode target,
 monotonic revision, ordered and available tiers, immutable Stripe Price ids,
 the membership-page renderer document, and explicitly delegated application,
 policy, scheduling, and theme sections. Theme tokens include typography as
-ordinary CSS custom properties such as `--ui-font-display` and
-`--ui-font-body`.
+allowlisted `--ui-*` CSS custom properties such as `--ui-font-display` and
+`--ui-font-sans`. Chapter rejects non-`--ui-*` names, non-finite values,
+oversized token sets, control characters, style-tag breakout, declaration
+breakout, comments, imports, expressions, and URL-bearing values. Application
+aliases such as `--teal` or `--deepocean` remain host-owned CSS.
 
 The packaged follower receiver validates the signed request timestamp, sender,
 target, environment, Stripe mode, schema, and SHA-256 digest. It rejects a stale
@@ -455,6 +458,84 @@ count before asking odla-db to order revision history. A freshly provisioned
 follower therefore acknowledges revision 1 immediately instead of depending on
 an ordered query over an empty result set.
 
+#### Render active tokens before first paint
+
+Put Chapter's marker after the local bootstrap theme and before any application
+boot script in the HTML head:
+
+```html
+<link rel="stylesheet" href="/bootstrap-theme.css">
+<!--odla:signup-control-theme-->
+<script type="module" src="/app.js"></script>
+```
+
+A host route can transform the static asset with the follower-local active row:
+
+```ts
+import { chapterWorker, withActiveSignupControlTheme } from "@odla-ai/chapter/worker";
+import { chapter } from "./chapter.config.mjs";
+
+export default chapterWorker({
+  chapter,
+  routes: [async (request, url, env, context) => {
+    if (request.method !== "GET" || url.pathname !== "/apply") return null;
+    const asset = await env.ASSETS.fetch(new URL("/index.html", url));
+    return withActiveSignupControlTheme(asset, {
+      db: context.makeDb(env),
+      chapterId: chapter.id,
+      environment: env.ODLA_ENV,
+      // The site's existing deterministic fallback when no revision is active.
+      bootstrapTokens: { "--ui-accent": "#096ea8" },
+    });
+  }],
+});
+```
+
+`withActiveSignupControlTheme` reads only the follower database, revalidates the
+stored document and its canonical digest, and injects one bounded style block
+with matching revision/digest metadata. It never calls the controlling hub. A
+missing active row emits the documented `bootstrap` state; a failed local read
+or corrupt active row fails closed instead of looking like absence. The response
+defaults to `Cache-Control: no-store`, carries digest/revision headers, and gets
+an ETag over the complete transformed HTML. This prevents a pre-activation page
+from surviving activation. A host-owned cache may instead call
+`renderActiveSignupControlHtml()` and include
+`result.theme.metadata.cacheKey` in its complete page cache key.
+
+For an SSR or static-HTML transform, use the same helper on the generated string:
+
+```ts
+import { renderActiveSignupControlHtml } from "@odla-ai/chapter/worker";
+
+const result = await renderActiveSignupControlHtml(generatedHtml, {
+  db, chapterId: chapter.id, environment,
+  bootstrapTokens: { "--ui-accent": "#096ea8" },
+});
+await writeHtml(result.html); // cache with result.theme.metadata.cacheKey
+```
+
+After `GET /api/join-config`, hydrate the existing style element rather than
+writing a second theme system. Matching revision/digest metadata produces no DOM
+write and therefore no visual token change:
+
+```ts
+import {
+  SIGNUP_CONTROL_THEME_STYLE_ID,
+  hydrateSignupControlTheme,
+} from "@odla-ai/chapter";
+
+const style = document.getElementById(SIGNUP_CONTROL_THEME_STYLE_ID);
+if (style instanceof HTMLStyleElement) {
+  hydrateSignupControlTheme(style, joinConfig.signupControl ?? null, {
+    bootstrapTokens: { "--ui-accent": "#096ea8" },
+  });
+}
+```
+
+The host still decides which routes use managed theming and owns any legacy
+token aliases. Keep the marker after bootstrap declarations so the active
+`--ui-*` values win in the initial parsed document.
+
 The hub owns a durable outbox: create/verify immutable Stripe Prices first,
 persist the desired revision, retry signed delivery, and mark it active only
 after the exact revision/digest receipt. Version history is for audit and

package/dist/index.cjs

@@ -27,6 +27,8 @@ __export(index_exports, {
   SCHEDULING_DEFAULTS: () => SCHEDULING_DEFAULTS,
   SIGNUP_CONTROL_PATH: () => SIGNUP_CONTROL_PATH,
   SIGNUP_CONTROL_SCHEMA_VERSION: () => SIGNUP_CONTROL_SCHEMA_VERSION,
+  SIGNUP_CONTROL_THEME_MARKER: () => SIGNUP_CONTROL_THEME_MARKER,
+  SIGNUP_CONTROL_THEME_STYLE_ID: () => SIGNUP_CONTROL_THEME_STYLE_ID,
   applicantProfile: () => applicantProfile,
   applicationBookingUpdate: () => applicationBookingUpdate,
   applicationSummary: () => applicationSummary,
@@ -70,6 +72,8 @@ __export(index_exports, {
   formationFields: () => formationFields,
   getVaultSecret: () => getVaultSecret,
   hasDisclaimerAck: () => hasDisclaimerAck,
+  hydrateSignupControlTheme: () => hydrateSignupControlTheme,
+  injectSignupControlThemeHead: () => injectSignupControlThemeHead,
   introIdempotencyKey: () => introIdempotencyKey,
   isAdminRole: () => isAdminRole,
   isAlreadySent: () => isAlreadySent,
@@ -99,6 +103,7 @@ __export(index_exports, {
   reconcileMeetings: () => reconcileMeetings,
   refundedPatch: () => refundedPatch,
   render: () => render,
+  renderSignupControlThemeHead: () => renderSignupControlThemeHead,
   renderSummary: () => renderSummary,
   renderTemplateBody: () => renderTemplateBody,
   renewalPatch: () => renewalPatch,
@@ -3026,12 +3031,18 @@ function themeOf(value, errors) {
   }
   unknownKeys(input, /* @__PURE__ */ new Set(["tokens"]), "document.theme", errors);
   if (Object.keys(tokens).length > 256) errors.push("document.theme.tokens supports at most 256 entries");
+  let serializedLength = 0;
   for (const [key, token] of Object.entries(tokens)) {
-    if (!/^--[a-z0-9-]{1,100}$/.test(key)) errors.push(`document.theme.tokens.${key} must be a CSS custom-property name`);
-    if (typeof token !== "string" && typeof token !== "number" || String(token).length > 1e3) {
-      errors.push(`document.theme.tokens.${key} must be a bounded string or number`);
+    if (!/^--ui-[a-z0-9][a-z0-9-]{0,94}$/.test(key)) {
+      errors.push(`document.theme.tokens.${key} must be an allowlisted --ui-* custom property`);
+    }
+    const rendered = String(token).trim();
+    serializedLength += key.length + rendered.length + 4;
+    if (typeof token !== "string" && typeof token !== "number" || typeof token === "number" && !Number.isFinite(token) || !rendered || rendered.length > 1e3 || /[\u0000-\u001f\u007f\\<>{};]|\/\*|\*\/|(?:^|[^a-z])(?:url|expression)\s*\(|@import/i.test(rendered)) {
+      errors.push(`document.theme.tokens.${key} must be a bounded breakout-safe CSS value`);
     }
   }
+  if (serializedLength > 65536) errors.push("document.theme.tokens exceeds the serialized size bound");
   return { tokens };
 }
 function validateSignupControlDocument(input) {
@@ -3083,6 +3094,116 @@ function validateSignupControlDocument(input) {
   } };
 }
 
+// src/signup-control-theme.ts
+var SIGNUP_CONTROL_THEME_MARKER = "<!--odla:signup-control-theme-->";
+var SIGNUP_CONTROL_THEME_STYLE_ID = "odla-signup-control-theme";
+var TOKEN_NAME = /^--ui-[a-z0-9][a-z0-9-]{0,94}$/;
+var DIGEST = /^sha256:[0-9a-f]{64}$/;
+var UNSAFE_VALUE = /[\u0000-\u001f\u007f\\<>{};]|\/\*|\*\/|(?:^|[^a-z])(?:url|expression)\s*\(|@import/i;
+var MAX_TOKENS = 256;
+var MAX_VALUE_LENGTH = 1e3;
+var MAX_SERIALIZED_LENGTH = 65536;
+function validatedTokens(input) {
+  const entries = Object.entries(input ?? {});
+  if (entries.length > MAX_TOKENS) {
+    throw new TypeError(`signup-control theme supports at most ${MAX_TOKENS} tokens`);
+  }
+  const tokens = {};
+  let serializedLength = 0;
+  for (const [name, raw] of entries.sort(([left], [right]) => left.localeCompare(right))) {
+    if (!TOKEN_NAME.test(name)) {
+      throw new TypeError(`signup-control theme token "${name}" must be an allowlisted --ui-* property`);
+    }
+    if (typeof raw !== "string" && typeof raw !== "number" || typeof raw === "number" && !Number.isFinite(raw)) {
+      throw new TypeError(`signup-control theme token "${name}" must be a finite string or number`);
+    }
+    const value = String(raw).trim();
+    if (!value || value.length > MAX_VALUE_LENGTH || UNSAFE_VALUE.test(value)) {
+      throw new TypeError(`signup-control theme token "${name}" has an unsafe or oversized value`);
+    }
+    serializedLength += name.length + value.length + 4;
+    if (serializedLength > MAX_SERIALIZED_LENGTH) {
+      throw new TypeError("signup-control theme exceeds the serialized size bound");
+    }
+    tokens[name] = value;
+  }
+  return tokens;
+}
+function cssFor(tokens) {
+  const declarations = Object.entries(tokens).map(([name, value]) => `  ${name}: ${value};`);
+  return declarations.length ? `:root {
+${declarations.join("\n")}
+}` : "";
+}
+function stateFor(revision, options) {
+  if (!revision) {
+    return {
+      css: cssFor(validatedTokens(options.bootstrapTokens)),
+      metadata: { source: "bootstrap", revision: null, digest: null, cacheKey: "signup-control:bootstrap" }
+    };
+  }
+  if (!Number.isSafeInteger(revision.revision) || revision.revision < 1 || !DIGEST.test(revision.digest)) {
+    throw new TypeError("signup-control theme revision metadata is invalid");
+  }
+  return {
+    css: cssFor(validatedTokens(revision.theme?.tokens)),
+    metadata: {
+      source: "active",
+      revision: revision.revision,
+      digest: revision.digest,
+      cacheKey: `signup-control:${revision.digest}`
+    }
+  };
+}
+function attributes(metadata) {
+  return [
+    `id="${SIGNUP_CONTROL_THEME_STYLE_ID}"`,
+    `data-signup-control-source="${metadata.source}"`,
+    `data-signup-control-cache-key="${metadata.cacheKey}"`,
+    ...metadata.revision === null ? [] : [`data-signup-control-revision="${metadata.revision}"`],
+    ...metadata.digest === null ? [] : [`data-signup-control-digest="${metadata.digest}"`]
+  ].join(" ");
+}
+function renderSignupControlThemeHead(revision, options = {}) {
+  const { css, metadata } = stateFor(revision, options);
+  return { css, metadata, head: `<style ${attributes(metadata)}>${css}</style>` };
+}
+function injectSignupControlThemeHead(html, rendered, marker = SIGNUP_CONTROL_THEME_MARKER) {
+  const existing = /<style\b(?=[^>]*\bid\s*=\s*["']odla-signup-control-theme["'])[^>]*>[\s\S]*?<\/style>/gi;
+  const existingBlocks = html.match(existing) ?? [];
+  if (existingBlocks.length > 1) {
+    throw new TypeError("signup-control theme style block must appear at most once");
+  }
+  if (existingBlocks.length === 1) return html.replace(existing, rendered.head);
+  const markerIndex = html.indexOf(marker);
+  if (markerIndex >= 0) {
+    if (html.indexOf(marker, markerIndex + marker.length) >= 0) {
+      throw new TypeError("signup-control theme marker must appear exactly once");
+    }
+    return `${html.slice(0, markerIndex)}${rendered.head}${html.slice(markerIndex + marker.length)}`;
+  }
+  const closingHead = html.search(/<\/head\s*>/i);
+  if (closingHead < 0) throw new TypeError("signup-control theme requires an HTML head");
+  return `${html.slice(0, closingHead)}${rendered.head}${html.slice(closingHead)}`;
+}
+function hydrateSignupControlTheme(target, revision, options = {}) {
+  const next = stateFor(revision, options);
+  const currentSource = target.getAttribute("data-signup-control-source");
+  const currentRevision = target.getAttribute("data-signup-control-revision");
+  const currentDigest = target.getAttribute("data-signup-control-digest");
+  if (currentSource === next.metadata.source && currentRevision === (next.metadata.revision === null ? null : String(next.metadata.revision)) && currentDigest === next.metadata.digest) {
+    return false;
+  }
+  target.textContent = next.css;
+  target.setAttribute("data-signup-control-source", next.metadata.source);
+  target.setAttribute("data-signup-control-cache-key", next.metadata.cacheKey);
+  if (next.metadata.revision === null) target.removeAttribute("data-signup-control-revision");
+  else target.setAttribute("data-signup-control-revision", String(next.metadata.revision));
+  if (next.metadata.digest === null) target.removeAttribute("data-signup-control-digest");
+  else target.setAttribute("data-signup-control-digest", next.metadata.digest);
+  return true;
+}
+
 // src/membership-markdown.ts
 var MAX_BENEFITS2 = 24;
 var MAX_MARKDOWN2 = 65536;