@legenki/studio-core 0.2.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024 Andy Legenki
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# @legenki/studio-core
+
+Shared runtime for the Legenki browser studios ([Grafema](https://github.com/legenki/grafema),
+[Ritmo](https://github.com/legenki/ritmo)).
+
+This package deliberately holds only the code where a **single source of truth
+matters** — auth, billing and the untrusted-input helpers. The apps' `shared/`
+directories have diverged substantially over time, and unifying all of them is a
+separate refactor. Keeping the surface small keeps the package easy to version.
+
+Consumed by **Grafema**, **Ritmo**, **Divix** and **Lumen**.
+
+## Install
+
+```bash
+npm install @legenki/studio-core
+```
+
+Or pin to a git tag, which is what the studios currently do — it needs no
+registry auth and makes the exact revision obvious in the lockfile:
+
+```json
+"@legenki/studio-core": "github:legenki/studio-core#v0.2.0"
+```
+
+Either way, pin deliberately: an unpinned dependency means a change here can
+break an app's deploy without a commit in that app.
+
+### Consumer setup
+
+The package ships untranspiled ES modules that read `import.meta.env`, so it
+expects a Vite (or equivalent) consumer. Vitest does not transform
+`node_modules` by default, so tests need it inlined:
+
+```js
+// vite.config.js / vitest.config.js
+test: {
+  server: { deps: { inline: ['@legenki/studio-core'] } },
+}
+```
+
+Without that, the package sees an undefined `import.meta.env` and throws on
+import.
+
+The paywall modal expects `.paywall-*` styles from the host app's stylesheet —
+the package ships no CSS.
+
+## Modules
+
+| Import | Purpose |
+| --- | --- |
+| `@legenki/studio-core/auth` | Supabase session, `checkPro()` subscription gate |
+| `@legenki/studio-core/paywall` | Subscription modal, Stripe payment-link redirect |
+| `@legenki/studio-core/deepMerge` | Preset merge, hardened against prototype pollution |
+| `@legenki/studio-core/datetime` | Filename-safe timestamp |
+
+### auth
+
+```js
+import { initAuth, checkPro, signIn, signOut } from '@legenki/studio-core/auth';
+
+initAuth({ onStateChange: (event, session, isPro) => updateUI(isPro) });
+```
+
+Requires `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY`. **Without them the
+module still imports cleanly** and the app runs signed-out in free mode — this is
+covered by `auth.unconfigured.test.js`, which exists because a module-level crash
+on a build without secrets shipped once before.
+
+Set `VITE_DEV_PRO=true` to bypass the gate in local development.
+
+Panels are usually built before auth resolves, so `checkPro()` reads false for
+everyone at construction time. Subscribe to be told when the real answer
+arrives, otherwise a subscriber sees the free UI until they reload:
+
+```js
+import { onProChange } from '@legenki/studio-core/auth';
+
+const unsubscribe = onProChange((isPro) => rebuildPanel(isPro));
+```
+
+### paywall
+
+Copy is per-app, so configure it once at startup before opening:
+
+```js
+import { configurePaywall, openPaywall } from '@legenki/studio-core/paywall';
+
+configurePaywall({
+  appName: 'Grafema',
+  subtitle: 'RETICULA, TEXTURA, RASTRO and MUESTRA, plus MP4 and SVG export.',
+  features: ['RETICULA — raster grid drawing', 'MP4 and SVG export'],
+  monthly: '$5',
+  yearly: '$40',
+});
+```
+
+Prices must match the app's landing page entry in `legenki-site`
+(`src/content/apps/<app>.md`) — the same offer is described in both places.
+
+The CTA appends `client_reference_id` (the Supabase user id) to the Stripe
+payment link; the `stripe-webhook` function uses it to map a completed checkout
+back to a user row.
+
+The modal expects `.paywall-*` styles from the host app's stylesheet.
+
+## Supabase keepalive
+
+`.github/workflows/supabase-keepalive.yml` queries the shared Supabase project
+every third day. The free tier pauses a project after ~7 days idle, which would
+take auth and Pro gating down across all four studios until someone restored it
+by hand.
+
+It queries through PostgREST rather than just pinging the project URL, because
+the pause check is based on database activity. An anonymous select returns `[]`
+under RLS — that is the healthy response; the point is that Postgres served a
+query. Needs `SUPABASE_URL` and `SUPABASE_ANON_KEY` repo secrets.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run lint
+```
+
+## Releasing
+
+Publishing is tag-driven, and the workflow refuses to publish when the tag and
+`package.json` disagree:
+
+```bash
+npm version patch     # or minor / major
+git push && git push --tags
+```
+
+That runs lint and tests, then publishes to npm with provenance. Needs an
+`NPM_TOKEN` repo secret.
+
+Because all four studios pin this package, a breaking change here should be a
+minor/major bump and a deliberate update in each consumer — never a silent
+in-place edit of a re-export inside an app repo.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@legenki/studio-core",
+  "version": "0.2.0",
+  "description": "Shared auth, paywall and utilities for the Legenki browser studios (Grafema, Ritmo, Divix, Lumen).",
+  "type": "module",
+  "license": "ISC",
+  "author": "Andy Legenki",
+  "homepage": "https://github.com/legenki/studio-core#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/legenki/studio-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/legenki/studio-core/issues"
+  },
+  "keywords": [
+    "supabase",
+    "stripe",
+    "paywall",
+    "subscription",
+    "auth"
+  ],
+  "sideEffects": false,
+  "files": [
+    "src",
+    "!src/__tests__"
+  ],
+  "exports": {
+    "./auth": "./src/auth.js",
+    "./paywall": "./src/paywall.js",
+    "./deepMerge": "./src/deepMerge.js",
+    "./datetime": "./src/datetime.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@supabase/supabase-js": "^2.108.0"
+  },
+  "peerDependenciesMeta": {
+    "@supabase/supabase-js": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "lint": "eslint src --max-warnings 0",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@supabase/supabase-js": "^2.108.2",
+    "eslint": "^10.4.1",
+    "globals": "^17.6.0",
+    "jsdom": "^29.1.1",
+    "vitest": "^4.1.8"
+  }
+}

package/src/auth.js

@@ -0,0 +1,110 @@
+import { createClient } from '@supabase/supabase-js';
+
+const SUPABASE_URL = import.meta.env.VITE_SUPABASE_URL;
+const SUPABASE_ANON_KEY = import.meta.env.VITE_SUPABASE_ANON_KEY;
+
+// Null when env is not configured (build without .env / CI secrets) —
+// the app then runs in signed-out free mode instead of crashing at load.
+export const supabase = SUPABASE_URL && SUPABASE_ANON_KEY
+  ? createClient(SUPABASE_URL, SUPABASE_ANON_KEY)
+  : null;
+
+if (!supabase) {
+  console.warn('[auth] Supabase env vars missing — auth disabled, running in free mode.');
+}
+
+// In-memory subscription cache — populated on auth state change
+let _subscription = null;
+
+// Test escape hatch — only used in auth.test.js
+export function _setSubscriptionForTest(sub) {
+  _subscription = sub;
+  notifyProChange();
+}
+
+/** Returns true if the current user has an active Pro subscription. */
+export function checkPro() {
+  if (import.meta.env.VITE_DEV_PRO === 'true') return true;
+  return _subscription?.status === 'active';
+}
+
+// Workspaces build their control panels before auth resolves, so `isPro` is
+// captured as false at construction. They subscribe here to rebuild once the
+// real answer arrives — otherwise a subscriber sees the free panel until they
+// reload. Kept separate from initAuth's single onStateChange, which the app
+// shell owns for the header UI.
+const _proListeners = new Set();
+
+/**
+ * Registers a callback fired whenever Pro state may have changed.
+ * @param {(isPro: boolean) => void} fn
+ * @returns {() => void} unsubscribe
+ */
+export function onProChange(fn) {
+  _proListeners.add(fn);
+  return () => _proListeners.delete(fn);
+}
+
+function notifyProChange() {
+  const pro = checkPro();
+  for (const fn of _proListeners) {
+    try {
+      fn(pro);
+    } catch (e) {
+      console.warn('[auth] pro listener failed:', e);
+    }
+  }
+}
+
+/** Fetches and caches the subscription row for the given user. */
+async function loadSubscription(userId) {
+  const { data, error } = await supabase
+    .from('subscriptions')
+    .select('status, plan, current_period_end')
+    .eq('user_id', userId)
+    .single();
+  _subscription = error ? null : data;
+}
+
+/**
+ * Initialise auth. Must be called once on page load.
+ * - Restores existing session automatically (returning users get Pro state on load)
+ * - Listens for sign-in / sign-out and reloads subscription accordingly
+ * - Returns the unsubscribe function
+ */
+export function initAuth({ onStateChange } = {}) {
+  if (!supabase) {
+    onStateChange?.(null, null, false);
+    return () => {};
+  }
+  const { data: { subscription } } = supabase.auth.onAuthStateChange(async (event, session) => {
+    if (session?.user) {
+      await loadSubscription(session.user.id);
+    } else {
+      _subscription = null;
+    }
+    notifyProChange();
+    onStateChange?.(event, session, checkPro());
+  });
+  return () => subscription.unsubscribe();
+}
+
+export function signIn() {
+  if (!supabase) return Promise.resolve(null);
+  return supabase.auth.signInWithOAuth({
+    provider: 'google',
+    options: { redirectTo: window.location.href },
+  });
+}
+
+export function signOut() {
+  _subscription = null;
+  if (!supabase) return Promise.resolve(null);
+  return supabase.auth.signOut();
+}
+
+export async function getSession() {
+  if (!supabase) return null;
+  const { data: { session } } = await supabase.auth.getSession();
+  return session;
+}

package/src/datetime.js

@@ -0,0 +1,14 @@
+/**
+ * Pure date/time helpers shared across workspaces (no p5 dependency).
+ */
+
+/**
+ * Filename-safe local timestamp: `YYYY-MM-DD_HH-MM-SS`.
+ * Used to suffix exported file names.
+ * @returns {string}
+ */
+export function timestamp() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}_${pad(d.getHours())}-${pad(d.getMinutes())}-${pad(d.getSeconds())}`;
+}

package/src/deepMerge.js

@@ -0,0 +1,27 @@
+/**
+ * Recursively merges `src` into `target`.
+ *
+ * Presets reach this function straight from a user-supplied .json file
+ * (see presetIO.openPresetFile), so the source object is untrusted: a preset
+ * containing `{"__proto__": {...}}` would otherwise walk into Object.prototype
+ * and pollute every object in the page. Keys that address the prototype chain
+ * are skipped outright — no legitimate preset needs them.
+ */
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+export function deepMerge(target, src) {
+  if (!src || typeof src !== 'object') return;
+  for (const key of Object.keys(src)) {
+    if (FORBIDDEN_KEYS.has(key)) continue;
+    const v = src[key];
+    if (v === undefined) continue;
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      if (!target[key] || typeof target[key] !== 'object') target[key] = {};
+      deepMerge(target[key], v);
+    } else if (Array.isArray(v)) {
+      target[key] = JSON.parse(JSON.stringify(v));
+    } else {
+      target[key] = v;
+    }
+  }
+}

package/src/paywall.js

@@ -0,0 +1,178 @@
+/**
+ * Subscription paywall modal.
+ *
+ * Ported from Ritmo, where the copy was hardcoded. Every app-specific string is
+ * now passed in via configure(), so Grafema and Ritmo share one implementation
+ * and one set of styles while advertising their own studios and prices.
+ *
+ * The plan prices shown here must match the app's landing page on legenki.com
+ * (src/content/apps/<app>.md) — they are the same offer described twice.
+ */
+
+import { signIn, getSession } from './auth.js';
+
+const STRIPE_MONTHLY_URL = import.meta.env.VITE_STRIPE_MONTHLY_URL;
+const STRIPE_YEARLY_URL = import.meta.env.VITE_STRIPE_YEARLY_URL;
+
+/** @type {HTMLElement|null} */
+let _modalEl = null;
+let _selectedPlan = 'yearly';
+
+/**
+ * @typedef {Object} PaywallConfig
+ * @property {string}   appName   e.g. "Grafema" — titles the modal.
+ * @property {string}   [subtitle] One-line summary of what Pro unlocks.
+ * @property {string[]} [features] Bullet list shown in the modal.
+ * @property {string}   [monthly]  Display price, e.g. "$5".
+ * @property {string}   [yearly]   Display price, e.g. "$40".
+ * @property {string}   [yearlyPerMonth] e.g. "$3.33 / month".
+ * @property {string}   [yearlyNote]     e.g. "Yearly · save 33%".
+ */
+
+/** @type {Required<PaywallConfig>} */
+const config = {
+  appName: 'Pro',
+  subtitle: '',
+  features: [],
+  monthly: '$5',
+  yearly: '$40',
+  yearlyPerMonth: '$3.33 / month',
+  yearlyNote: 'Yearly · save 33%',
+};
+
+/**
+ * Sets the app-specific copy. Call once at startup, before openPaywall().
+ * Re-configuring discards any modal already built so the new copy takes effect.
+ * @param {PaywallConfig} options
+ */
+export function configurePaywall(options = {}) {
+  Object.assign(config, options);
+  if (_modalEl) {
+    _modalEl.remove();
+    _modalEl = null;
+  }
+}
+
+function escapeHtml(value) {
+  return String(value).replace(
+    /[&<>"']/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]
+  );
+}
+
+function ctaLabel() {
+  return _selectedPlan === 'yearly'
+    ? `Subscribe — ${config.yearly} / year →`
+    : `Subscribe — ${config.monthly} / month →`;
+}
+
+function getModal() {
+  if (_modalEl) return _modalEl;
+
+  _modalEl = document.createElement('div');
+  _modalEl.id = 'paywall-modal';
+  _modalEl.setAttribute('role', 'dialog');
+  _modalEl.setAttribute('aria-modal', 'true');
+  _modalEl.setAttribute('aria-label', `${config.appName} Pro`);
+  _modalEl.style.display = 'none';
+  _modalEl.innerHTML = `
+    <div class="paywall-backdrop"></div>
+    <div class="paywall-box">
+      <button class="paywall-close" aria-label="Close">✕</button>
+      <div class="paywall-eyebrow">${escapeHtml(config.appName)} Pro</div>
+      <div class="paywall-title">Unlock everything</div>
+      <div class="paywall-sub">${escapeHtml(config.subtitle)}</div>
+      <ul class="paywall-features">
+        ${config.features.map((f) => `<li>${escapeHtml(f)}</li>`).join('')}
+      </ul>
+      <div class="paywall-pricing">
+        <div class="paywall-plan" data-plan="monthly">
+          <div class="paywall-plan-label">Monthly</div>
+          <div class="paywall-plan-amount">${escapeHtml(config.monthly)}</div>
+          <div class="paywall-plan-period">per month</div>
+        </div>
+        <div class="paywall-plan selected" data-plan="yearly">
+          <div class="paywall-plan-label">${escapeHtml(config.yearlyNote)}</div>
+          <div class="paywall-plan-amount">${escapeHtml(config.yearly)}</div>
+          <div class="paywall-plan-period">${escapeHtml(config.yearlyPerMonth)}</div>
+        </div>
+      </div>
+      <button class="paywall-cta btn btn-accent">${escapeHtml(ctaLabel())}</button>
+      <div class="paywall-footer">
+        Cancel anytime · Powered by Stripe ·
+        Already subscribed? <a class="paywall-signin-link">Sign in</a>
+      </div>
+    </div>
+  `;
+
+  document.body.appendChild(_modalEl);
+
+  _modalEl.querySelector('.paywall-backdrop').addEventListener('click', closePaywall);
+  _modalEl.querySelector('.paywall-close').addEventListener('click', closePaywall);
+  _modalEl.querySelector('.paywall-signin-link').addEventListener('click', () => {
+    closePaywall();
+    signIn();
+  });
+
+  _modalEl.querySelectorAll('.paywall-plan').forEach((el) => {
+    el.addEventListener('click', () => {
+      _selectedPlan = el.dataset.plan;
+      _modalEl.querySelectorAll('.paywall-plan').forEach((p) => p.classList.remove('selected'));
+      el.classList.add('selected');
+      _modalEl.querySelector('.paywall-cta').textContent = ctaLabel();
+    });
+  });
+
+  _modalEl.querySelector('.paywall-cta').addEventListener('click', async () => {
+    const base = _selectedPlan === 'yearly' ? STRIPE_YEARLY_URL : STRIPE_MONTHLY_URL;
+    if (!base) {
+      console.warn('[paywall] Stripe payment link not configured.');
+      return;
+    }
+    // client_reference_id is how the Stripe webhook maps the completed checkout
+    // back to a Supabase user row (see supabase/functions/stripe-webhook).
+    const session = await getSession();
+    window.location.href = session?.user
+      ? `${base}?client_reference_id=${encodeURIComponent(session.user.id)}`
+      : base;
+  });
+
+  return _modalEl;
+}
+
+export function openPaywall() {
+  const modal = getModal();
+  modal.style.display = 'flex';
+  document.body.style.overflow = 'hidden';
+}
+
+export function closePaywall() {
+  if (!_modalEl) return;
+  _modalEl.style.display = 'none';
+  document.body.style.overflow = '';
+}
+
+/**
+ * If the URL contains ?checkout=success, refresh auth state and show a toast.
+ * Call once on page load after initAuth().
+ * @param {() => Promise<unknown>} refreshFn
+ */
+export function handleCheckoutSuccess(refreshFn) {
+  const url = new URL(window.location.href);
+  if (url.searchParams.get('checkout') !== 'success') return;
+  url.searchParams.delete('checkout');
+  window.history.replaceState({}, '', url.toString());
+  refreshFn().then(() => showToast('Welcome to Pro ✦'));
+}
+
+function showToast(message) {
+  const toast = document.createElement('div');
+  toast.className = 'paywall-toast';
+  toast.textContent = message;
+  document.body.appendChild(toast);
+  setTimeout(() => toast.classList.add('visible'), 10);
+  setTimeout(() => {
+    toast.classList.remove('visible');
+    setTimeout(() => toast.remove(), 300);
+  }, 3000);
+}