@wenathlan/cobaia 2.0.164 → 2.0.166

package/cobaia.csproj

@@ -4,7 +4,7 @@
     <AssemblyName>cobaia</AssemblyName>
     <RootNamespace>cobaia</RootNamespace>
     <PackageId>cobaia</PackageId>
-    <Version>2.0.164</Version>
+    <Version>2.0.166</Version>
     <Authors>wenathlan</Authors>
     <Description>Distribution package containing the cobaia documentation set and the tests directory. cobaia is the monetization surface — the plans, the support rails and the honest advertisement slots.</Description>
     <PackageLicenseExpression>GPL-3.0-only</PackageLicenseExpression>

package/cobaia.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name = "cobaia"
-  spec.version = ENV.fetch("COBAIA_VERSION", "2.0.164")
+  spec.version = ENV.fetch("COBAIA_VERSION", "2.0.166")
   spec.authors = ["wenathlan"]
   spec.email = ["support@users.noreply.github.com"]
   spec.summary = "The cobaia documentation and tests envelope (the monetization surface — the plans, the support rails and the honest advertisement slots)."

package/cobaia.java

@@ -1,4 +1,4 @@
-package io.github.wenathlan.cobaia;
+package com.wenathlan.cobaia;
 
 /**
  * The cobaia version envelope carrier.
@@ -10,7 +10,7 @@ package io.github.wenathlan.cobaia;
  */
 final class Cobaia {
   /** The version of the cobaia envelope (the six-distribution completeness wave). */
-  public static final String VERSION = "2.0.164";
+  public static final String VERSION = "2.0.166";
   private Cobaia() {
   }
 }

package/db.ts

@@ -5,14 +5,15 @@
  * concatenation. The schema mirrors schema.prisma (the documentation of
  * record) and the boot DDL is the idempotent seed-on-first-run: the tables
  * exist after the first open, always. The platform gateway serves the same
- * tables over HTTPS (GET/POST /api/v1/onboarding); no server route lives
- * here.
+ * tables over HTTPS (GET/POST /api/v1/onboarding, GET /api/v1/ui/content);
+ * no server route lives here.
  */
 import { openStorageLane } from "@wenathlan/vault/storage";
+import { CONTENTKINDS, type contentrow, seedAdsLabel, seedAdsEmpty, seedAdsSlots, seedPlans, seedPosts, seedRoster, seedSupportLinks } from "./content";
 import { LABEL_MANIFEST, LABEL_REVISION } from "./labels";
 
 /** the correlated tables the runtime keeps (the family sync contract names). */
-export const tables = ["onboarding_states", "labels"] as const;
+export const tables = ["onboarding_states", "labels", "content_rows"] as const;
 
 /** the one storage lane of the site store (WAL, foreign keys, patient locks — the app's own file, the shared mechanism of the vault). */
 const lane = openStorageLane({ defaultFile: "./cobaia.db" });
@@ -41,6 +42,12 @@ CREATE TABLE IF NOT EXISTS labels (
   updatedAt  TEXT NOT NULL DEFAULT (datetime('now')),
   translated INTEGER NOT NULL DEFAULT 0
 );
+CREATE TABLE IF NOT EXISTS content_rows (
+  kind     TEXT NOT NULL,
+  ordinal  INTEGER NOT NULL,
+  payload  TEXT NOT NULL,
+  PRIMARY KEY (kind, ordinal)
+);
 `;
 
 /** Creates the tables when they do not exist (idempotent, mirrors the prisma schema). */
@@ -217,3 +224,80 @@ try {
 } catch {
   /* the manifest answers; the store catches up on the next boot */
 }
+
+/* --------------------------------------------------------------------- */
+/* content rows — the site content the pages render                       */
+/* --------------------------------------------------------------------- */
+
+/** the manifest seed of one content kind: the rows in ordinal order. */
+function seedrowsOf(kind: (typeof CONTENTKINDS)[number]): readonly unknown[] {
+  switch (kind) {
+    case "posts":
+      return seedPosts;
+    case "roster":
+      return seedRoster;
+    case "plans":
+      return seedPlans;
+    case "supportlinks":
+      return [seedSupportLinks];
+    case "ads.slots":
+      return [seedAdsSlots];
+    case "ads.label":
+      return [seedAdsLabel];
+    case "ads.empty":
+      return [seedAdsEmpty];
+  }
+}
+
+/** Encodes the manifest rows of every kind as content rows (kind, ordinal,
+ * json payload) — the encoding the api answers and the client loader parses. */
+function seedContentRows(): contentrow[] {
+  const rows: contentrow[] = [];
+  for (const kind of CONTENTKINDS) {
+    seedrowsOf(kind).forEach((value, ordinal) => {
+      rows.push({ kind, ordinal, payload: JSON.stringify(value) });
+    });
+  }
+  return rows;
+}
+
+/**
+ * Ingests the content manifest into the content_rows table — idempotent:
+ * every manifest row upserts over its (kind, ordinal) seat, so the db stays
+ * the single living config of the site content the pages render (the
+ * content law: the literals live in the manifest, the rows live here).
+ *
+ * @returns the number of rows seated.
+ */
+export function seedContentTable(): number {
+  ensureSchema();
+  for (const row of seedContentRows()) {
+    execute(
+      `INSERT INTO content_rows (kind, ordinal, payload) VALUES (?, ?, ?)
+       ON CONFLICT(kind, ordinal) DO UPDATE SET payload = excluded.payload`,
+      [row.kind, row.ordinal, row.payload],
+    );
+  }
+  return seedContentRows().length;
+}
+
+/**
+ * Reads every content row of the store, ordered by kind then ordinal — the
+ * rows the platform gateway answers over GET /api/v1/ui/content.
+ *
+ * @returns the content rows of the site store.
+ */
+export function readContentRows(): contentrow[] {
+  return queryAll<Pick<contentrow, "kind" | "ordinal" | "payload">>(
+    "SELECT kind, ordinal, payload FROM content_rows ORDER BY kind ASC, ordinal ASC",
+  ).map((row) => ({ kind: row.kind as contentrow["kind"], ordinal: row.ordinal, payload: row.payload }));
+}
+
+/* the content law rides the db boot beside the labels: the manifest rows
+ * land in the content_rows table from the first open, always (idempotent,
+ * best effort — the manifest keeps answering when the store is sealed). */
+try {
+  seedContentTable();
+} catch {
+  /* the manifest answers; the store catches up on the next boot */
+}

package/docs/cobaia.md

@@ -0,0 +1,31 @@
+# cobaia — the dossier
+
+The public monetization surface of the family: plans, MRR tracking, honest ad slots and the support rails.
+
+## Identity
+
+- Category: monetization surface.
+- Competitor space: GitHub Sponsors, Ko-fi honest monetization.
+
+## Objective
+
+Give the family an honest monetization engine: every plan grants resources (never powers), every ad slot stays empty until approval, every rail is public and auditable.
+
+## Features
+
+- Plans: the resource grants the devthink system sells (storage quotas, engine seats).
+- MRR tracking and churn seats.
+- Ad slots that stay empty until the approval flows answer (zero tracking before approval).
+- Support rails: sponsorship links, badges, roster.
+- Billing seats with the honest playbook: cashback becomes store credit, never real money.
+- Absolute ethical limits codified: no invisible click mirroring, no dark patterns.
+
+## Interactions
+
+- Public surface with banner, plans and support sections.
+- The roster of supporters and the honest badges.
+
+## Doctrine
+
+- Honest monetization: every limit is a plan limit, never an engine limit.
+- Ethical absolute: the ad seat refuses to track before the approval answers.

package/docs/distributionlanes.md

@@ -6,7 +6,7 @@ The eleven distribution lanes of the PR14 law and the honest status each lane an
 | --- | --- | --- | --- |
 | npmjs | package.json — @wenathlan/cobaia | live | the family-npmjs lane publishes the envelope every release rung |
 | GitHub Packages npm | package.json — @wenathlan/cobaia | live | the family-githubnpm lane publishes the same envelope idempotently |
-| Maven | pom.xml — io.github.wenathlan:cobaia | live | the family-maven lane deploys the jar |
+| Maven | pom.xml — com.wenathlan:cobaia | live | the family-maven lane deploys the jar |
 | NuGet | cobaia.csproj | live | the family-nuget lane packs the envelope |
 | Gradle | build.gradle.kts — com.wenathlan:cobaia | live | the family-gradle lane publishes the module |
 | Ruby Gems | cobaia.gemspec | live | the family-rubygems lane pushes the gem |

package/labels.ts

@@ -26,7 +26,7 @@ import { createLabelStore } from "@wenathlan/vault/labelstore";
 
 /** the label revision of the manifest: bump on every copy wave so the seed
  * refreshes the store rows of the changed strings. */
-export const LABEL_REVISION = 4;
+export const LABEL_REVISION = 5;
 
 /** the english manifest: the page.widget.key path answers the surface text.
  * every entry is the verbatim string the wingets and page anchors rendered
@@ -257,6 +257,28 @@ export const LABEL_MANIFEST = {
   "intro.footer.familyAria": "the family row",
   "intro.footer.family": "the family",
   "intro.footer.memberTip": "open {slug} — the door beside this site",
+  // the onboarding page anchor (the first-run frames of the entry flow —
+  // the standardized intro → onboarding → entrada law the family rides;
+  // cobaia's frames present the real offer: what the site is, what it
+  // carries, and the hand-over to the content pages)
+  "onboarding.aria": "cobaia — the first-run steps",
+  "onboarding.title": "cobaia",
+  "onboarding.skip": "skip — straight to the site",
+  "onboarding.back": "back",
+  "onboarding.next": "next",
+  "onboarding.enterCta": "enter the site",
+  "onboarding.steps.is.eyebrow": "01 — what this is",
+  "onboarding.steps.is.title": "The family's front door.",
+  "onboarding.steps.is.text": "cobaia is the monetization face of the devthink family — the front door kept apart so the ten applications stay clean. the directory, the plans, the support channels and the update blog live on this one static site.",
+  "onboarding.steps.does.eyebrow": "02 — what it carries",
+  "onboarding.steps.does.title": "The plans, the support rails, the honest ads.",
+  "onboarding.steps.does.text": "the real offer, nothing invented: the three plans with their placeholder prices said out loud, the support rails that activate when the owner wires them, and the reserved ad boxes that stay empty until a network approves the site.",
+  "onboarding.steps.enter.eyebrow": "03 — the entrada",
+  "onboarding.steps.enter.title": "One responsive site, every screen.",
+  "onboarding.steps.enter.text": "the same responsive pages answer on the phone, the tv, the extension and the desktop — the presentation adapts, the content never changes. the entrada is the front door itself.",
+  "onboarding.facts.plans": "the plans — us$0, 5 and 19 a month, placeholder prices until billing lands, honest until then",
+  "onboarding.facts.support": "the support rails — the sponsor channels, configured the day the owner wires them",
+  "onboarding.facts.ads": "the ad slots — reserved boxes, visibly labeled, empty until a network approves the site",
   // the ad slot widget (the reserved box of the content pages)
   "ads.slot.reserved": "reserved · {format}",
 } as const;

package/onboardingstate.ts

@@ -0,0 +1,211 @@
+/**
+ * onboardingstate.ts — the ONE writer of the visitor's seen flags, the state
+ * of the entry-flow contract (intro → onboarding → the site). The state is
+ * { introseen, onboardingseen } and it is catalogued, not just browser: the
+ * accessor consults the platform database over GET /api/v1/onboarding and
+ * writes it over POST /api/v1/onboarding, both HTTPS only — the base url
+ * arrives through VITE_ONBOARDING_URL and every candidate host is validated
+ * first (localhost, loopback, private, CGNAT, link-local and reserved ranges
+ * are refused, mapped IPv6 is normalized, so the flags never ride a dev or
+ * internal endpoint). The localStorage key cobaia.onboarding.seen is purely
+ * the offline cache of the database (the DB is the source of truth; the
+ * cache avoids replaying the flow while offline) and module memory covers
+ * the client-side re-navigation between the gates. Reads reconcile with a
+ * seen-wins merge — a stage seen anywhere stays seen, the flow is never
+ * forced twice. The page anchors never touch the flags directly: the intro
+ * marks introseen, the onboarding marks onboardingseen, the home entry gate
+ * only reads (the family flow contract the sibling apps already ride —
+ * cobaia joins the standardized intro → onboarding → entrada law).
+ */
+
+/** the visitor state the entry flow consults (the two gates of the site). */
+export type VisitorOnboarding = {
+  /** the presentation intro was seen — the splash never replays */
+  introseen: boolean;
+  /** the first-run onboarding was seen (finish or skip) — never forced again */
+  onboardingseen: boolean;
+};
+
+/** the stages one call can mark seen. */
+export type OnboardingStage = "intro" | "onboarding";
+
+/** the localStorage cache key (the DB mirror, never the source of truth). */
+const CACHE_KEY = "cobaia.onboarding.seen";
+
+/** the anonymous visitor of this surface (the platform gateway may key its own). */
+const VISITOR = "web";
+
+/** the configured platform base (HTTPS self-hosted gateway); empty answers cache-only. */
+const BASE =
+  (typeof import.meta !== "undefined" ? (import.meta.env?.VITE_ONBOARDING_URL as string | undefined) : undefined)
+    ?.trim()
+    .replace(/\/+$/, "") ?? "";
+
+/** the platform route the accessor rides (the gateway serves /api/v1/*). */
+const API_PATH = "/api/v1/onboarding";
+
+/** the abort window of the platform read (ms) — the flow never blocks on a slow gateway. */
+const READ_TIMEOUT_MS = 2500;
+
+/** module memory: the flags of the session, consulted before any i/o. */
+let memory: VisitorOnboarding | null = null;
+
+/**
+ * Validates a platform base url: HTTPS only, and the host must be public —
+ * localhost, loopback, private, link-local, CGNAT, unique-local and
+ * reserved documentation ranges are refused; IPv4-mapped IPv6 literals are
+ * normalized to their IPv4 side and any other IPv6 literal is refused (the
+ * gateway rides a name).
+ *
+ * @param base the configured base url candidate.
+ * @returns true when the base may be consulted.
+ */
+export function hostallowed(base: string): boolean {
+  try {
+    const url = new URL(base);
+    if (url.protocol !== "https:") return false;
+    const host = url.hostname
+      .toLowerCase()
+      .replace(/\.+$/, "")
+      .replace(/^\[|\]$/g, "");
+    if (host.length === 0) return false;
+    if (host === "localhost" || host === "0.0.0.0" || host === "::1") return false;
+    if (host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal")) return false;
+    // the ipv4-mapped ipv6 form (the url parser normalizes the decimals away)
+    if (host.startsWith("::ffff:")) {
+      const mapped = host.slice("::ffff:".length).match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+      return mapped !== null && publicipv4(Number(mapped[1]), Number(mapped[2]));
+    }
+    const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (v4) return publicipv4(Number(v4[1]), Number(v4[2]));
+    // every other ipv6 literal: the gateway rides a name, not an address
+    if (host.includes(":")) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** the public side of an ipv4 address (the first two octets decide). */
+function publicipv4(a: number, b: number): boolean {
+  if (a === 0 || a === 10 || a === 127) return false;
+  if (a === 172 && b >= 16 && b <= 31) return false;
+  if (a === 192 && b === 168) return false;
+  if (a === 169 && b === 254) return false;
+  if (a === 100 && b >= 64 && b <= 127) return false;
+  if (a === 192 && b === 0) return false;
+  if (a === 198 && (b === 51 || b === 52)) return false;
+  if (a === 203 && b === 0) return false;
+  return true;
+}
+
+/**
+ * Answers the flags after one stage was marked seen (pure: the writer and
+ * the tests share this merge — seen-wins, a stage never unsees).
+ *
+ * @param state the flags before the write.
+ * @param stage the stage being marked seen.
+ * @returns the flags after the write.
+ */
+export function mergeStage(state: VisitorOnboarding, stage: OnboardingStage): VisitorOnboarding {
+  return stage === "intro" ? { ...state, introseen: true } : { ...state, onboardingseen: true };
+}
+
+/** Reads the localStorage cache; any corruption answers null (the cache is best effort). */
+function readCache(): VisitorOnboarding | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(CACHE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<VisitorOnboarding>;
+    return { introseen: parsed.introseen === true, onboardingseen: parsed.onboardingseen === true };
+  } catch {
+    return null;
+  }
+}
+
+/** Mirrors the flags into the localStorage cache (silently skipped when storage is sealed). */
+function writeCache(state: VisitorOnboarding): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(CACHE_KEY, JSON.stringify(state));
+  } catch {
+    // the cache is best effort: the DB and the memory stay authoritative
+  }
+}
+
+/** Reads the flags off the platform database; unreachable or unconfigured answers null. */
+async function readRemote(): Promise<VisitorOnboarding | null> {
+  if (!BASE || !hostallowed(BASE) || typeof fetch === "undefined") return null;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), READ_TIMEOUT_MS);
+  try {
+    const response = await fetch(`${BASE}${API_PATH}?visitor=${encodeURIComponent(VISITOR)}`, {
+      headers: { accept: "application/json" },
+      signal: controller.signal,
+    });
+    if (!response.ok) return null;
+    const answer = (await response.json()) as Partial<VisitorOnboarding>;
+    return { introseen: answer.introseen === true, onboardingseen: answer.onboardingseen === true };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Writes the flags to the platform database over POST; failures leave the cache holding them. */
+async function writeRemote(state: VisitorOnboarding): Promise<void> {
+  if (!BASE || !hostallowed(BASE) || typeof fetch === "undefined") return;
+  try {
+    await fetch(`${BASE}${API_PATH}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ visitor: VISITOR, ...state }),
+    });
+  } catch {
+    // the cache mirrors the flags until the platform answers again
+  }
+}
+
+/**
+ * Reads the visitor state: module memory first, then the platform database
+ * over GET /api/v1/onboarding, then the localStorage cache — reconciled with
+ * the seen-wins merge so a stage seen anywhere stays seen. The session
+ * answer is memoized; re-navigation never refetches.
+ *
+ * @returns the visitor onboarding flags.
+ */
+export async function readOnboardingState(): Promise<VisitorOnboarding> {
+  if (memory) return memory;
+  const cache = readCache();
+  const remote = await readRemote();
+  const state: VisitorOnboarding = {
+    introseen: (cache?.introseen ?? false) || (remote?.introseen ?? false),
+    onboardingseen: (cache?.onboardingseen ?? false) || (remote?.onboardingseen ?? false),
+  };
+  memory = state;
+  if (remote) writeCache(state);
+  return state;
+}
+
+/**
+ * Marks one stage seen and persists it everywhere: module memory, the
+ * localStorage cache and — when a platform base is configured — the
+ * database over POST /api/v1/onboarding. The ONLY writer of the flags.
+ *
+ * @param stage the stage the visitor just saw (or deliberately skipped).
+ * @returns the flags after the write.
+ */
+export async function markOnboardingStage(stage: OnboardingStage): Promise<VisitorOnboarding> {
+  const previous = memory ?? (await readOnboardingState());
+  memory = mergeStage(previous, stage);
+  writeCache(memory);
+  await writeRemote(memory);
+  return memory;
+}
+
+/** Test seam: clears the module memory (the cache and the platform are untouched). */
+export function resetOnboardingMemory(): void {
+  memory = null;
+}