@odla-ai/chapter 0.34.0 → 0.36.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