npm - @crossworks/share-ui - Versions diffs - 0.232.64 → 0.232.66 - Mend

@crossworks/share-ui 0.232.64 → 0.232.66

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@crossworks/share-ui",
-  "version": "0.232.64",
+  "version": "0.232.66",
   "description": "The server-rendered share surface — the /s/<token> presenters, view-payload contract, mini-app sandbox, and the few primitives they need. Lives in MANTLE (the server renders these), published for jackdaw to consume; may depend only on @mantle/{client-types,content-core} (the jackdaw-repo-split boundary).",
   "exports": {
     "./app-presenter": "./src/app-presenter.tsx",
@@ -25,6 +25,9 @@
     "./nav-items": "./src/nav-items.ts",
     "./help-topics": "./src/help-topics.ts",
     "./appearance": "./src/appearance.ts",
+    "./neat-background": "./src/neat-background.ts",
+    "./neat-mount": "./src/neat-mount.ts",
+    "./share-mode": "./src/share-mode.ts",
     "./backgrounds": "./src/backgrounds.ts",
     "./avatar": "./src/avatar.ts",
     "./lib/themes": "./src/lib/themes.ts",
@@ -32,8 +35,9 @@
     "./styles/app.css": "./styles/app.css"
   },
   "dependencies": {
-    "@mantle/client-types": "npm:@crossworks/client-types@0.232.64",
-    "@mantle/content-core": "npm:@crossworks/content-core@0.232.64",
+    "@firecms/neat": "1.0.2",
+    "@mantle/client-types": "npm:@crossworks/client-types@0.232.66",
+    "@mantle/content-core": "npm:@crossworks/content-core@0.232.66",
     "@radix-ui/react-label": "^2.1.12",
     "@radix-ui/react-slot": "^1.3.0",
     "class-variance-authority": "^0.7.1",

package/src/appearance.ts CHANGED Viewed

@@ -55,6 +55,24 @@ export type BrainAppearance = {
   avatarStyle: string | null;
   avatarTint: string | null;
   backgrounds: string | null;
+  /** The generated whole-surface Neat gradient's spec, compact JSON
+   *  `{v,seed,tone,speed}` — colours derive from the live theme client-side.
+   *  NOT stamped onto `<html>`: it feeds a WebGL component, not the CSS.
+   *  Optional for the published-contract reason below: readers treat absence
+   *  as "not set" and paint the plain themed fill. */
+  neatBackground?: string | null;
+  /** The brain's default light/dark mode for surfaces where the visitor has
+   *  not chosen one (the public /s share reader): 'light' | 'dark' | 'system'.
+   *  NOT stamped onto `<html>` by resolveAppearanceAttrs — the share renderer
+   *  applies it as the `.dark` class itself, and the client app ignores it
+   *  (in-app mode stays the visitor's own next-themes choice). Optional for
+   *  the published-contract reason below; absence reads as 'light', the share
+   *  surface's historical rendering. */
+  defaultMode?: string | null;
+  /** Whether shared surfaces (/s, the team workspace) paint the saved Neat
+   *  gradient at all — false is the printable plain fallback. NOT stamped onto
+   *  `<html>`; readers treat absence as true (the default). */
+  shareNeat?: boolean | null;
   /**
    * WHO this brain is — its own name, the name of the box, and whether an
    * uploaded logo exists. Unlike everything above these are NOT stamped onto

package/src/neat-background.ts ADDED Viewed

@@ -0,0 +1,216 @@
+import type { NeatConfig } from '@firecms/neat';
+/**
+ * The Neat background — an animated WebGL gradient behind a whole surface,
+ * generated in Settings → Appearance and stored on the brain's preferences
+ * row. This module is the spec contract and the parameter derivation; it lives
+ * HERE (published as @crossworks/share-ui) because two renderers consume it —
+ * the jackdaw owner app (login screen, content area) and this repo's
+ * server-rendered /s share surface — and the two must never disagree about
+ * what a saved spec looks like.
+ *
+ * We store a SPEC, never colours: `{ v, seed, tone, speed }`. Every colour is
+ * derived from the LIVE theme tokens at paint time, so one saved background
+ * follows all ~40 colour themes and light/dark mode by construction — a
+ * stored hex would break silently on most themes, exactly like a hardcoded
+ * class would. The seed drives a deterministic PRNG for every other Neat
+ * parameter, so "the background I saved" is reproducible from four numbers,
+ * and "Generate" is just a re-roll of the seed.
+ *
+ * The derived colours are washes: each brand colour is pulled most of the way
+ * into `--background` before it reaches the shader. That is the legibility
+ * guarantee — the gradient reads as a tint of the page surface, never a
+ * poster fighting the text sitting on it.
+ */
+export type NeatTone = 'auto' | 'darker' | 'lighter';
+export type NeatBackgroundSpec = {
+  v: 1;
+  /** Seeds the PRNG that derives every Neat parameter. */
+  seed: number;
+  /** Push the wash below the page surface ('darker'), above it ('lighter'),
+   *  or follow the mode — dark mode darkens, light mode lightens ('auto'). */
+  tone: NeatTone;
+  /** Animation speed, 0 (still) to {@link NEAT_SPEED_MAX}. */
+  speed: number;
+};
+export const NEAT_SPEED_MAX = 6;
+export const NEAT_DEFAULT_SPEED = 2;
+/** Storage cap, mirrored by the server route — the canonical encoding of a
+ *  valid spec is ~60 chars, so this is a garbage guard, not a limit. */
+export const NEAT_BACKGROUND_MAX = 200;
+const TONES: readonly NeatTone[] = ['auto', 'darker', 'lighter'];
+/** Canonical wire encoding — fixed key order so equal specs compare equal as
+ *  strings (the UI's dirty check and the renderer's effect key rely on it). */
+export function encodeNeatSpec(spec: NeatBackgroundSpec): string {
+  return JSON.stringify({ v: 1, seed: spec.seed, tone: spec.tone, speed: spec.speed });
+}
+/** Parse + shape-check a stored value. Garbage ⇒ null, never a throw — the
+ *  same lenient contract every appearance preference follows on read. */
+export function decodeNeatSpec(raw: unknown): NeatBackgroundSpec | null {
+  if (typeof raw !== 'string' || raw.length === 0 || raw.length > NEAT_BACKGROUND_MAX) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  const o = parsed as Record<string, unknown>;
+  if (o.v !== 1) return null;
+  if (typeof o.seed !== 'number' || !Number.isInteger(o.seed) || o.seed < 0 || o.seed > 0xffffffff)
+    return null;
+  if (typeof o.tone !== 'string' || !(TONES as readonly string[]).includes(o.tone)) return null;
+  if (typeof o.speed !== 'number' || !Number.isFinite(o.speed) || o.speed < 0) return null;
+  return {
+    v: 1,
+    seed: o.seed,
+    tone: o.tone as NeatTone,
+    speed: Math.min(o.speed, NEAT_SPEED_MAX),
+  };
+}
+export function randomNeatSpec(
+  prev?: Pick<NeatBackgroundSpec, 'tone' | 'speed'>,
+): NeatBackgroundSpec {
+  return {
+    v: 1,
+    seed: Math.floor(Math.random() * 0xffffffff),
+    tone: prev?.tone ?? 'auto',
+    speed: prev?.speed ?? NEAT_DEFAULT_SPEED,
+  };
+}
+/** The tokens the shader needs, resolved to literal hex — WebGL cannot read
+ *  `var()`, same constraint as the DiceBear ramp in theme-ramp.ts. */
+export type NeatThemeTokens = {
+  background: string;
+  primary: string;
+  accent: string;
+  secondary: string;
+};
+/** Deterministic PRNG (mulberry32) — same seed, same background, forever. */
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+function hexToRgb(hex: string): [number, number, number] | null {
+  const digits = /^#?([0-9a-f]{6})$/i.exec(hex.trim())?.[1];
+  if (!digits) return null;
+  const n = parseInt(digits, 16);
+  return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+}
+function rgbToHex([r, g, b]: [number, number, number]): string {
+  const c = (v: number) =>
+    Math.max(0, Math.min(255, Math.round(v)))
+      .toString(16)
+      .padStart(2, '0');
+  return `#${c(r)}${c(g)}${c(b)}`;
+}
+/** `amount` of `into` mixed over `from` — 0 keeps `from`, 1 lands on `into`. */
+function mixHex(from: string, into: string, amount: number): string {
+  const a = hexToRgb(from);
+  const b = hexToRgb(into);
+  if (!a || !b) return from;
+  return rgbToHex([
+    a[0] + (b[0] - a[0]) * amount,
+    a[1] + (b[1] - a[1]) * amount,
+    a[2] + (b[2] - a[2]) * amount,
+  ]);
+}
+/** Nudge toward black (factor < 1) or white (factor > 1). */
+function shadeHex(hex: string, factor: number): string {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return hex;
+  if (factor <= 1) return rgbToHex([rgb[0] * factor, rgb[1] * factor, rgb[2] * factor]);
+  const up = factor - 1;
+  return rgbToHex([
+    rgb[0] + (255 - rgb[0]) * up,
+    rgb[1] + (255 - rgb[1]) * up,
+    rgb[2] + (255 - rgb[2]) * up,
+  ]);
+}
+const round1 = (n: number) => Math.round(n * 10) / 10;
+const round2 = (n: number) => Math.round(n * 100) / 100;
+/**
+ * Spec + live tokens + mode → the full Neat config (minus `ref`/`resolution`,
+ * which are the renderer's business). Pure and deterministic, so the settings
+ * preview and the real surface can never disagree about what a saved spec
+ * looks like.
+ */
+export function neatConfigFromSpec(
+  spec: NeatBackgroundSpec,
+  tokens: NeatThemeTokens,
+  mode: 'light' | 'dark',
+): NeatConfig {
+  const rnd = mulberry32(spec.seed);
+  const range = (lo: number, hi: number) => lo + rnd() * (hi - lo);
+  const darker = spec.tone === 'darker' || (spec.tone === 'auto' && mode === 'dark');
+  // A wash: pull the brand colour part-way into the page background, then
+  // nudge the result off the surface in the chosen direction. Enough colour
+  // to read as a real gradient, close enough to the surface that content
+  // sitting on it never fights it.
+  const wash = (hex: string, towardBg: number) =>
+    shadeHex(mixHex(hex, tokens.background, towardBg), darker ? 0.88 : 1.08);
+  return {
+    colors: [
+      { color: tokens.background, enabled: true, influence: round2(range(0.3, 0.6)) },
+      {
+        color: wash(tokens.primary, round2(range(0.25, 0.5))),
+        enabled: true,
+        influence: round2(range(0.5, 0.9)),
+      },
+      {
+        color: wash(tokens.accent, round2(range(0.25, 0.55))),
+        enabled: true,
+        influence: round2(range(0.45, 0.85)),
+      },
+      {
+        color: wash(tokens.secondary, round2(range(0.35, 0.6))),
+        enabled: true,
+        influence: round2(range(0.35, 0.75)),
+      },
+      { color: tokens.background, enabled: true, influence: round2(range(0.25, 0.55)) },
+    ],
+    speed: spec.speed,
+    horizontalPressure: round1(range(2, 5)),
+    verticalPressure: round1(range(2, 5)),
+    waveFrequencyX: round1(range(2, 6)),
+    waveFrequencyY: round1(range(2, 6)),
+    waveAmplitude: round1(range(3, 7)),
+    // Keep the shader's own light play gentle: strong shadows/highlights are
+    // exactly what would carve text-hostile contrast into the surface.
+    shadows: round1(range(0, darker ? 3 : 1.5)),
+    highlights: round1(range(0, darker ? 1.5 : 3)),
+    colorBrightness: darker ? 0.95 : 1,
+    colorSaturation: round1(range(-1, 2.5)),
+    colorBlending: round1(range(5, 9)),
+    grainScale: 2,
+    grainIntensity: round2(range(0.02, 0.1)),
+    grainSpeed: 0.3,
+    wireframe: false,
+    backgroundColor: tokens.background,
+    backgroundAlpha: 1,
+  };
+}

package/src/neat-mount.ts ADDED Viewed

@@ -0,0 +1,82 @@
+import {
+  neatConfigFromSpec,
+  type NeatBackgroundSpec,
+  type NeatThemeTokens,
+} from './neat-background';
+/**
+ * The one true way to put a Neat spec onto a canvas — shared by every
+ * renderer (the /s reader's vanilla runtime here in mantle; jackdaw's React
+ * NeatBackdrop wraps it too), so the hard-won WebGL specifics live exactly
+ * once:
+ *
+ *  - `@firecms/neat` is dynamically imported HERE, so every consumer's
+ *    bundler splits the ~80KB WebGL chunk out and only fetches it on
+ *    surfaces that actually paint a gradient.
+ *  - Colours are read off the live document per call — shaders take
+ *    literals, not `var()` — and an unresolvable theme mounts NOTHING
+ *    rather than a wrong guess; the themed surface underneath is the
+ *    designed fallback.
+ *  - Neat's `seed` is NOT a randomness seed: it is the animation clock's
+ *    starting value (u_time, fp32 on the GPU). A raw 32-bit seed exceeds
+ *    fp32 precision and collapses the shader's small offsets into ONE FLAT
+ *    COLOUR. It is modded into the library's own clock range here; the full
+ *    seed still drives the parameter PRNG.
+ *  - `prefers-reduced-motion` freezes the animation (speed 0); the wash
+ *    still paints.
+ *
+ * TIMING is the caller's job: mount only after the document's theme
+ * class/attributes have settled (in practice, from a requestAnimationFrame
+ * callback), or the tokens read here belong to the OUTGOING theme. So is
+ * CANCELLATION: this resolves after an await, so a caller that has moved on
+ * must destroy the returned handle instead of keeping it.
+ */
+export type NeatMountHandle = { destroy: () => void };
+/** The four tokens the shader derives every colour from, resolved to literal
+ *  values off the live document. Null when the theme is unresolvable (a test
+ *  DOM, a broken stylesheet) — paint nothing rather than a wrong guess. */
+export function readNeatThemeTokens(): NeatThemeTokens | null {
+  const cs = getComputedStyle(document.documentElement);
+  const read = (name: string) => cs.getPropertyValue(name).trim();
+  const tokens = {
+    background: read('--background'),
+    primary: read('--primary'),
+    accent: read('--accent'),
+    secondary: read('--secondary'),
+  };
+  return tokens.background && tokens.primary ? tokens : null;
+}
+/**
+ * Build the gradient onto `canvas`. Resolves to a handle to destroy, or null
+ * when nothing mounted (unresolvable theme, WebGL unavailable) — null is the
+ * designed fallback, never an error.
+ */
+export async function mountNeat(
+  canvas: HTMLCanvasElement,
+  spec: NeatBackgroundSpec,
+  mode: 'light' | 'dark',
+  opts: { resolution?: number; licenseKey?: string } = {},
+): Promise<NeatMountHandle | null> {
+  const { NeatGradient } = await import('@firecms/neat');
+  const tokens = readNeatThemeTokens();
+  if (!tokens) return null;
+  const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  const config = neatConfigFromSpec(spec, tokens, mode);
+  try {
+    return new NeatGradient({
+      ...config,
+      ref: canvas,
+      seed: spec.seed % 3600,
+      resolution: opts.resolution ?? 1,
+      speed: reduced ? 0 : config.speed,
+      ...(opts.licenseKey ? { licenseKey: opts.licenseKey } : {}),
+    });
+  } catch {
+    // WebGL unavailable (headless browser, exhausted contexts).
+    return null;
+  }
+}

package/src/share-mode.ts ADDED Viewed

@@ -0,0 +1,12 @@
+/**
+ * The /s reader's visitor mode contract — deliberately its own tiny module:
+ * the share-page browser runtime imports it, and routing it through
+ * appearance.ts would drag the avatar/font/background registries into a
+ * bundle that exists to stay small.
+ */
+/** The localStorage key holding a /s VISITOR's own light/dark choice — theirs
+ *  alone, never the owner's. Two bundles must agree on it: the server's
+ *  pre-paint inline script (template.ts) writes the reader, the share-page
+ *  runtime writes the value. One constant, no mirrored literal. */
+export const SHARE_MODE_STORAGE_KEY = 'mantle-share-mode';