npm - @crossworks/share-ui - Versions diffs - 0.232.65 → 0.232.67 - Mend

@crossworks/share-ui 0.232.65 → 0.232.67

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 (6) hide show

package/package.json +7 -3
package/src/appearance.ts +12 -0
package/src/neat-background.test.ts +58 -0
package/src/neat-background.ts +249 -0
package/src/neat-mount.ts +82 -0
package/src/share-mode.ts +12 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@crossworks/share-ui",
-  "version": "0.232.65",
+  "version": "0.232.67",
   "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.65",
-    "@mantle/content-core": "npm:@crossworks/content-core@0.232.65",
+    "@firecms/neat": "1.0.2",
+    "@mantle/client-types": "npm:@crossworks/client-types@0.232.67",
+    "@mantle/content-core": "npm:@crossworks/content-core@0.232.67",
     "@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

@@ -61,6 +61,18 @@ export type BrainAppearance = {
    *  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.test.ts ADDED Viewed

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { decodeNeatSpec, encodeNeatSpec, neatConfigFromSpec } from './neat-background';
+const SPEC = { v: 1 as const, seed: 2325271021, tone: 'auto' as const, speed: 2 };
+describe('decodeNeatSpec', () => {
+  it('round-trips the canonical encoding', () => {
+    expect(decodeNeatSpec(encodeNeatSpec(SPEC))).toEqual(SPEC);
+  });
+  it('rejects garbage as null, never a throw', () => {
+    for (const bad of [null, '', '{}', '{"v":2}', 'not json', '{"v":1,"seed":-1}']) {
+      expect(decodeNeatSpec(bad)).toBeNull();
+    }
+  });
+});
+describe('neatConfigFromSpec — the wash', () => {
+  const long = {
+    background: '#ffffff',
+    primary: '#b85c23',
+    accent: '#eeeeee',
+    secondary: '#527575',
+  };
+  // What getComputedStyle actually returns on a deployed build: the compiled
+  // stylesheet minifies hex custom properties to shorthand where possible.
+  const short = { background: '#fff', primary: '#b85c23', accent: '#eee', secondary: '#527575' };
+  it('produces the IDENTICAL config for shorthand #rgb and #rrggbb tokens', () => {
+    // Whole-config equality on purpose: it pins the wash (a failed shorthand
+    // parse degraded stops to the raw brand colour) AND the raw pass-throughs
+    // (colors[0]/[4] and backgroundColor once carried '#fff' verbatim, which
+    // Neat's parseInt-based parser reads as 0x000fff — electric blue).
+    expect(neatConfigFromSpec(SPEC, short, 'light')).toEqual(
+      neatConfigFromSpec(SPEC, long, 'light'),
+    );
+  });
+  it('hands the shader only canonical six-digit hex, never shorthand', () => {
+    const c = neatConfigFromSpec(SPEC, short, 'light');
+    for (const stop of c.colors) expect(stop.color).toMatch(/^#[0-9a-f]{6}$/);
+    expect(c.backgroundColor).toBe('#ffffff');
+  });
+  it('actually washes the brand colour toward the ground', () => {
+    const washed = neatConfigFromSpec(SPEC, short, 'light').colors[1]?.color ?? '';
+    // Raw primary (or its 1.08 shade, #c66c39-ish) means the mix silently
+    // failed; a washed stop is much lighter than the brand colour.
+    expect(washed).not.toBe('#b85c23');
+    const mean =
+      [1, 3, 5].map((i) => parseInt(washed.slice(i, i + 2), 16)).reduce((s, n) => s + n, 0) / 3;
+    expect(mean).toBeGreaterThan(150);
+  });
+  it('is deterministic — same seed, same config', () => {
+    expect(neatConfigFromSpec(SPEC, long, 'dark')).toEqual(neatConfigFromSpec(SPEC, long, 'dark'));
+  });
+});

package/src/neat-background.ts ADDED Viewed

@@ -0,0 +1,249 @@
+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 t = hex.trim();
+  // Shorthand #rgb MUST parse: the compiled stylesheets minify hex custom
+  // properties (#ffffff → #fff, #eeeeee → #eee), so this is what
+  // getComputedStyle actually returns on deployed builds. Rejecting it made
+  // mixHex silently return the RAW brand colour — no wash, a saturated
+  // poster instead of a tint — on exactly the themes whose tokens shorten,
+  // and only in production (dev CSS is unminified). Light modes were hit
+  // hardest because near-white grounds (#ffffff/#eeeeee) all shorten.
+  const short = /^#?([0-9a-f]{3})$/i.exec(t)?.[1];
+  if (short) {
+    const c = (i: number) => parseInt(short.charAt(i) + short.charAt(i), 16);
+    return [c(0), c(1), c(2)];
+  }
+  const digits = /^#?([0-9a-f]{6})$/i.exec(t)?.[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,
+  ]);
+}
+/** Canonical #rrggbb for any hex this module can parse; unparseable values
+ *  pass through untouched. EVERY colour handed to the shader goes through
+ *  this: Neat's own parser is `parseInt(hex, 16)` on whatever it gets, so a
+ *  shorthand `#fff` reads as the 24-bit int 0x000fff — rgb(0, 15, 255), an
+ *  electric blue poster where the page ground should be. That is precisely
+ *  what deployed light themes produced, because minified stylesheets shorten
+ *  near-white tokens to #fff/#eee. */
+function normalizeHex(hex: string): string {
+  const rgb = hexToRgb(hex);
+  return rgb ? rgbToHex(rgb) : hex;
+}
+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');
+  // Tokens arrive as whatever getComputedStyle returns — on deployed builds
+  // that includes minifier shorthand. Normalized ONCE here, so both our wash
+  // math and the raw pass-throughs below hand the shader canonical hex.
+  const background = normalizeHex(tokens.background);
+  const primary = normalizeHex(tokens.primary);
+  const accent = normalizeHex(tokens.accent);
+  const secondary = normalizeHex(tokens.secondary);
+  // 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, background, towardBg), darker ? 0.88 : 1.08);
+  return {
+    colors: [
+      { color: background, enabled: true, influence: round2(range(0.3, 0.6)) },
+      {
+        color: wash(primary, round2(range(0.25, 0.5))),
+        enabled: true,
+        influence: round2(range(0.5, 0.9)),
+      },
+      {
+        color: wash(accent, round2(range(0.25, 0.55))),
+        enabled: true,
+        influence: round2(range(0.45, 0.85)),
+      },
+      {
+        color: wash(secondary, round2(range(0.35, 0.6))),
+        enabled: true,
+        influence: round2(range(0.35, 0.75)),
+      },
+      { color: 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: 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';