@cosxai/ui 0.1.0

package/src/pwa/InstallPromptBanner.tsx

@@ -0,0 +1,132 @@
+import { useEffect, useState } from "react";
+import { Button } from "../primitives/Button";
+
+// Surfaces the browser's PWA install affordance — `beforeinstallprompt`
+// is the Chromium-side hook that fires when a site qualifies for
+// install. Without intervention browsers eventually suppress it; we
+// catch the event, render a dismissable banner, and trigger the
+// prompt only when the user clicks Install.
+//
+// Dismissal persists in localStorage so the banner doesn't reappear
+// on every page load after the user said no thanks.
+//
+// iOS Safari doesn't fire beforeinstallprompt at all — for that
+// platform you need to show your own "Tap share → Add to Home
+// Screen" instructions. Detect via `iosSafari` prop or your own
+// heuristic and render a different banner if needed.
+
+interface BeforeInstallPromptEvent extends Event {
+  prompt: () => Promise<void>;
+  userChoice: Promise<{ outcome: "accepted" | "dismissed" }>;
+}
+
+export interface InstallPromptBannerProps {
+  // Heading text.
+  title?: string;
+  // Body text below the heading.
+  message?: string;
+  installLabel?: string;
+  dismissLabel?: string;
+  // localStorage key for the dismissal flag.
+  storageKey?: string;
+  // Called after the user installs (accepted) or dismisses.
+  onResolve?: (outcome: "accepted" | "dismissed") => void;
+}
+
+export function InstallPromptBanner({
+  title = "Install this app",
+  message = "Add it to your home screen for a faster, full-screen experience.",
+  installLabel = "Install",
+  dismissLabel = "Not now",
+  storageKey = "ck-install-prompt-dismissed",
+  onResolve,
+}: InstallPromptBannerProps) {
+  const [evt, setEvt] = useState<BeforeInstallPromptEvent | null>(null);
+  const [dismissed, setDismissed] = useState(() => {
+    if (typeof window === "undefined") return true;
+    return window.localStorage.getItem(storageKey) === "1";
+  });
+
+  useEffect(() => {
+    if (dismissed) return;
+    const onBefore = (e: Event) => {
+      e.preventDefault();
+      setEvt(e as BeforeInstallPromptEvent);
+    };
+    window.addEventListener("beforeinstallprompt", onBefore);
+    return () => window.removeEventListener("beforeinstallprompt", onBefore);
+  }, [dismissed]);
+
+  const dismiss = () => {
+    window.localStorage.setItem(storageKey, "1");
+    setDismissed(true);
+    setEvt(null);
+    onResolve?.("dismissed");
+  };
+
+  const install = async () => {
+    if (!evt) return;
+    await evt.prompt();
+    const choice = await evt.userChoice;
+    setEvt(null);
+    if (choice.outcome === "accepted") {
+      window.localStorage.setItem(storageKey, "1");
+      setDismissed(true);
+    }
+    onResolve?.(choice.outcome);
+  };
+
+  if (dismissed || !evt) return null;
+
+  return (
+    <div
+      role="region"
+      aria-label="Install app"
+      style={{
+        position: "fixed",
+        left: 16,
+        right: 16,
+        bottom: `calc(16px + var(--ck-tabbar-height, 0px))`,
+        zIndex: 90,
+        maxWidth: 480,
+        marginLeft: "auto",
+        marginRight: "auto",
+        background: "var(--ck-bg-surface)",
+        border: "1px solid var(--ck-border-subtle)",
+        borderRadius: "var(--ck-radius-md)",
+        boxShadow: "var(--ck-shadow-2)",
+        padding: "14px 16px",
+        display: "flex",
+        gap: 12,
+        alignItems: "center",
+        fontFamily: "var(--ck-font-sans)",
+      }}
+    >
+      <div style={{ flex: 1, minWidth: 0 }}>
+        <div
+          style={{
+            font: "500 14px/1.3 var(--ck-font-sans)",
+            color: "var(--ck-text-primary)",
+            marginBottom: 2,
+          }}
+        >
+          {title}
+        </div>
+        <div
+          style={{
+            font: "400 12px/1.4 var(--ck-font-sans)",
+            color: "var(--ck-text-tertiary)",
+          }}
+        >
+          {message}
+        </div>
+      </div>
+      <Button variant="ghost" onClick={dismiss}>
+        {dismissLabel}
+      </Button>
+      <Button variant="primary" onClick={install}>
+        {installLabel}
+      </Button>
+    </div>
+  );
+}

package/src/pwa/index.ts

@@ -0,0 +1,4 @@
+export { InstallPromptBanner } from "./InstallPromptBanner";
+export type { InstallPromptBannerProps } from "./InstallPromptBanner";
+export { registerSW } from "./registerSW";
+export type { RegisterSWOptions } from "./registerSW";

package/src/pwa/manifest.template.json

@@ -0,0 +1,20 @@
+{
+  "name": "Your App Name",
+  "short_name": "AppName",
+  "description": "One-line app description.",
+  "start_url": "/",
+  "display": "standalone",
+  "orientation": "portrait",
+  "theme_color": "#0B0D12",
+  "background_color": "#0B0D12",
+  "icons": [
+    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" },
+    {
+      "src": "/icon-512-maskable.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ]
+}

package/src/pwa/registerSW.ts

@@ -0,0 +1,55 @@
+// Thin wrapper around vite-plugin-pwa's `virtual:pwa-register`. Use
+// from your app's entry point (main.tsx) so the service worker is
+// registered on first paint. Behaviour:
+//
+//   - new SW detected → optional onNeedRefresh callback (typically
+//     toast prompting reload)
+//   - SW activated for the first time → onOfflineReady callback
+//     (typically toast announcing "Ready offline")
+//
+// The kit doesn't pull in vite-plugin-pwa as a dep — the consumer
+// app installs and configures it. This wrapper just centralises
+// the registration boilerplate so consumers don't repeat it.
+
+export interface RegisterSWOptions {
+  onNeedRefresh?: () => void;
+  onOfflineReady?: () => void;
+  onRegistered?: (registration: ServiceWorkerRegistration | undefined) => void;
+  onRegisterError?: (error: unknown) => void;
+}
+
+// Specifier is constructed from a runtime expression so Vite's
+// static import analyser can't see "virtual:pwa-register" as a
+// literal — without this, every consumer app would fail to boot
+// unless they had vite-plugin-pwa installed AND configured (since
+// transform happens before the try/catch runs at runtime).
+//
+// The eval is the simplest indirection that's also obviously a
+// no-op to readers. /* @vite-ignore */ on its own isn't enough
+// because Vite still attempts resolution when the specifier is a
+// constant string literal.
+const PWA_REGISTER_SPECIFIER = ["virtual", "pwa-register"].join(":");
+
+export async function registerSW(opts: RegisterSWOptions = {}) {
+  if (typeof window === "undefined") return;
+  try {
+    const mod = await import(/* @vite-ignore */ PWA_REGISTER_SPECIFIER);
+    if (typeof mod.registerSW !== "function") {
+      console.warn("virtual:pwa-register found but registerSW() is not a function");
+      return;
+    }
+    mod.registerSW({
+      immediate: true,
+      onNeedRefresh: opts.onNeedRefresh,
+      onOfflineReady: opts.onOfflineReady,
+      onRegisteredSW: (_url: string, reg: ServiceWorkerRegistration | undefined) => {
+        opts.onRegistered?.(reg);
+      },
+      onRegisterError: opts.onRegisterError,
+    });
+  } catch (err) {
+    // vite-plugin-pwa not installed / configured. Silent in dev,
+    // surface to caller if they care.
+    opts.onRegisterError?.(err);
+  }
+}

package/src/riso/Halftone.tsx

@@ -0,0 +1,85 @@
+import type { CSSProperties, ReactNode } from "react";
+
+// Halftone-tinted image / fill block. Renders a solid ink-color
+// background with a halftone dot pattern overlay; if `src` is
+// provided, the image sits underneath in `mix-blend-mode: multiply`
+// for a duotone-on-paper feel.
+//
+// Use for hero blocks, empty-state illustrations, photo treatments.
+
+export interface HalftoneProps {
+  children?: ReactNode;
+  // Optional image source. The image is duotoned via blend modes.
+  src?: string;
+  alt?: string;
+  // Ink color of the dot fill. Defaults to riso pink.
+  ink?: string;
+  // Dot size in px. Defaults to 1.6.
+  dotSize?: number;
+  // Dot grid spacing in px. Defaults to 7.
+  dotSpacing?: number;
+  width?: number | string;
+  height?: number | string;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function Halftone({
+  children,
+  src,
+  alt = "",
+  ink = "var(--ck-riso-pink, #FF48B0)",
+  dotSize = 1.6,
+  dotSpacing = 7,
+  width = "100%",
+  height = 200,
+  className,
+  style,
+}: HalftoneProps) {
+  return (
+    <div
+      className={className}
+      style={{
+        position: "relative",
+        width,
+        height,
+        background: ink,
+        overflow: "hidden",
+        borderRadius: 4,
+        ...style,
+      }}
+    >
+      {src && (
+        <img
+          src={src}
+          alt={alt}
+          style={{
+            position: "absolute",
+            inset: 0,
+            width: "100%",
+            height: "100%",
+            objectFit: "cover",
+            mixBlendMode: "multiply",
+            filter: "grayscale(1) contrast(1.15)",
+            pointerEvents: "none",
+          }}
+        />
+      )}
+      <div
+        aria-hidden
+        style={{
+          position: "absolute",
+          inset: 0,
+          pointerEvents: "none",
+          backgroundImage: `radial-gradient(circle, rgba(26,26,26,0.85) ${dotSize}px, transparent ${dotSize + 0.2}px)`,
+          backgroundSize: `${dotSpacing}px ${dotSpacing}px`,
+          mixBlendMode: "multiply",
+          opacity: 0.55,
+        }}
+      />
+      {children && (
+        <div style={{ position: "relative", zIndex: 2, color: "#1A1A1A" }}>{children}</div>
+      )}
+    </div>
+  );
+}

package/src/riso/Misregister.tsx

@@ -0,0 +1,63 @@
+import type { CSSProperties, ReactNode } from "react";
+
+// Misregistration — render text (or any child) twice, with a small
+// offset between an "under" duplicate in a second ink color and the
+// "top" pass in the primary ink. The signature riso effect.
+//
+// The under copy is set aria-hidden so screen readers don't double-
+// read the content.
+
+export interface MisregisterProps {
+  children?: ReactNode;
+  // Ink color of the foreground (top) pass.
+  ink?: string;
+  // Ink color of the misregistered duplicate. Defaults to riso pink.
+  offsetInk?: string;
+  // Offset of the duplicate, in px. Defaults to {x:3, y:3}.
+  offsetX?: number;
+  offsetY?: number;
+  // Wrap in inline-block? Defaults true. Pass false for block use.
+  inline?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function Misregister({
+  children,
+  ink,
+  offsetInk = "var(--ck-riso-pink, #FF48B0)",
+  offsetX = 3,
+  offsetY = 3,
+  inline = true,
+  className,
+  style,
+}: MisregisterProps) {
+  return (
+    <span
+      className={className}
+      style={{
+        display: inline ? "inline-block" : "block",
+        position: "relative",
+        color: ink ?? "var(--ck-text-primary)",
+        ...style,
+      }}
+    >
+      <span
+        aria-hidden
+        style={{
+          position: "absolute",
+          top: offsetY,
+          left: offsetX,
+          color: offsetInk,
+          mixBlendMode: "multiply",
+          pointerEvents: "none",
+          width: "100%",
+          height: "100%",
+        }}
+      >
+        {children}
+      </span>
+      <span style={{ position: "relative" }}>{children}</span>
+    </span>
+  );
+}

package/src/riso/RisoStamp.tsx

@@ -0,0 +1,76 @@
+import type { CSSProperties, ReactNode } from "react";
+
+// Hand-stamped label — slightly rotated, bordered, with an offset
+// ink block "shadow." The riso equivalent of a Tag but louder.
+// Use for "NEW", "LIMITED", "ED. 01", "OUT NOW" annotations
+// layered over photos / hero blocks.
+
+export interface RisoStampProps {
+  children?: ReactNode;
+  // Ink color of the stamp face. Defaults to pink.
+  ink?: "pink" | "blue" | "yellow" | "orange" | "teal" | "violet" | "red" | "green";
+  // Ink color of the offset block behind. Defaults to ink-black.
+  offset?: "pink" | "blue" | "yellow" | "orange" | "teal" | "violet" | "red" | "green" | "ink";
+  // Rotation in degrees. Defaults to -4.
+  rotate?: number;
+  // Larger / smaller sizing presets.
+  size?: "sm" | "md" | "lg";
+  className?: string;
+  style?: CSSProperties;
+}
+
+const INKS: Record<string, string> = {
+  pink:   "var(--ck-riso-pink, #FF48B0)",
+  blue:   "var(--ck-riso-blue, #3D5AFE)",
+  yellow: "var(--ck-riso-yellow, #FFE100)",
+  orange: "var(--ck-riso-orange, #FF6F3C)",
+  teal:   "var(--ck-riso-teal, #00A99D)",
+  violet: "var(--ck-riso-violet, #765BA7)",
+  red:    "var(--ck-riso-red, #F02D2D)",
+  green:  "var(--ck-riso-green, #00A95C)",
+  ink:    "var(--ck-text-primary, #1A1A1A)",
+};
+
+const SIZES = {
+  sm: { font: 10, padX: 6, padY: 3, offset: 2 },
+  md: { font: 12, padX: 10, padY: 5, offset: 3 },
+  lg: { font: 16, padX: 14, padY: 7, offset: 4 },
+} as const;
+
+export function RisoStamp({
+  children,
+  ink = "pink",
+  offset = "ink",
+  rotate = -4,
+  size = "md",
+  className,
+  style,
+}: RisoStampProps) {
+  const inkColor = INKS[ink] ?? INKS.pink;
+  const offsetColor = INKS[offset] ?? INKS.ink;
+  const s = SIZES[size];
+  // Yellow / lime ink reads better with dark text.
+  const lightOnDark = ink === "yellow" || ink === "orange" || ink === "green" || ink === "pink";
+  return (
+    <span
+      className={className}
+      style={{
+        display: "inline-block",
+        background: inkColor,
+        color: lightOnDark ? "#1A1A1A" : "#F8F1DE",
+        border: "2px solid #1A1A1A",
+        borderRadius: 4,
+        padding: `${s.padY}px ${s.padX}px`,
+        font: `800 ${s.font}px/1 "Helvetica Neue", "Inter", system-ui, sans-serif`,
+        letterSpacing: "0.08em",
+        textTransform: "uppercase",
+        boxShadow: `${s.offset}px ${s.offset}px 0 ${offsetColor}`,
+        transform: `rotate(${rotate}deg)`,
+        whiteSpace: "nowrap",
+        ...style,
+      }}
+    >
+      {children}
+    </span>
+  );
+}

package/src/riso/index.ts

@@ -0,0 +1,3 @@
+export * from "./RisoStamp";
+export * from "./Misregister";
+export * from "./Halftone";

package/src/sketch/HandUnderline.tsx

@@ -0,0 +1,53 @@
+import type { CSSProperties, ReactNode } from "react";
+
+// Wraps a string of text with a hand-drawn underline. The
+// underline is a CSS-only wobble using the same SVG-filter trick
+// the chrome uses on hr / .ck-card head strokes. Falls back to a
+// solid 2px line in browsers that ignore the data-URL filter.
+
+export interface HandUnderlineProps {
+  children?: ReactNode;
+  // Underline color. Defaults to the current text color.
+  ink?: string;
+  // Thickness in px. Defaults to 2.
+  thickness?: number;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function HandUnderline({
+  children,
+  ink = "currentColor",
+  thickness = 2,
+  className,
+  style,
+}: HandUnderlineProps) {
+  return (
+    <span
+      className={className}
+      style={{
+        position: "relative",
+        display: "inline-block",
+        paddingBottom: 2,
+        ...style,
+      }}
+    >
+      {children}
+      <span
+        aria-hidden
+        style={{
+          position: "absolute",
+          left: 0,
+          right: 0,
+          bottom: -1,
+          height: thickness,
+          background: ink,
+          borderRadius: thickness,
+          filter: "var(--ck-sketch-wobble)",
+          opacity: 0.85,
+          pointerEvents: "none",
+        }}
+      />
+    </span>
+  );
+}

package/src/sketch/RoughArrow.tsx

@@ -0,0 +1,91 @@
+import type { CSSProperties } from "react";
+
+// Inline SVG hand-drawn arrow. Used between elements on a canvas
+// to indicate connection / flow, or as an annotation pointer.
+// The path is hand-tuned to feel drawn, not generated — small
+// kinks, asymmetric arrowhead. Stroke color + width controllable.
+//
+// The arrow draws on via stroke-dasharray animation on mount when
+// `animated` is true.
+
+export interface RoughArrowProps {
+  // Endpoints in px (relative to the SVG's own coordinate space).
+  from?: [number, number];
+  to?: [number, number];
+  // Stroke color. Defaults to ink.
+  ink?: string;
+  // Stroke thickness. Defaults to 2.
+  thickness?: number;
+  // Curve amount — 0 is a straight wobble, 1 is a strong arc.
+  curve?: number;
+  // Animate the draw-on. Defaults to false (instant).
+  animated?: boolean;
+  width?: number | string;
+  height?: number | string;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function RoughArrow({
+  from = [10, 40],
+  to = [220, 40],
+  ink = "var(--ck-text-primary, #1A1A1A)",
+  thickness = 2,
+  curve = 0.4,
+  animated = false,
+  width = 240,
+  height = 80,
+  className,
+  style,
+}: RoughArrowProps) {
+  const [x1, y1] = from;
+  const [x2, y2] = to;
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+  const len = Math.sqrt(dx * dx + dy * dy);
+  // Perpendicular for the control offsets — produces a gentle arc.
+  const px = -dy / len;
+  const py = dx / len;
+  // Two control points with tiny irregular wobble.
+  const cx1 = x1 + dx * 0.3 + px * len * curve * 0.4;
+  const cy1 = y1 + dy * 0.3 + py * len * curve * 0.4;
+  const cx2 = x1 + dx * 0.7 + px * len * curve * 0.5 + 2;
+  const cy2 = y1 + dy * 0.7 + py * len * curve * 0.5 - 1;
+
+  const path = `M ${x1} ${y1} C ${cx1} ${cy1}, ${cx2} ${cy2}, ${x2} ${y2}`;
+
+  // Arrowhead — two strokes meeting at (x2,y2). Length and angle
+  // pre-computed from the (cx2 → x2) direction.
+  const ahLen = 14;
+  const angle = Math.atan2(y2 - cy2, x2 - cx2);
+  const aOpen = 0.45;
+  const ax1 = x2 - Math.cos(angle - aOpen) * ahLen;
+  const ay1 = y2 - Math.sin(angle - aOpen) * ahLen;
+  const ax2 = x2 - Math.cos(angle + aOpen) * ahLen;
+  const ay2 = y2 - Math.sin(angle + aOpen) * ahLen;
+
+  // Pen-press effect — slightly thicker stroke at start/end via
+  // overlaid short paths. Keeps SVG light, no shaders.
+  return (
+    <svg
+      className={className}
+      width={width}
+      height={height}
+      viewBox={`0 0 ${typeof width === "number" ? width : 240} ${typeof height === "number" ? height : 80}`}
+      style={{ overflow: "visible", display: "block", ...style }}
+      aria-hidden
+    >
+      <g
+        fill="none"
+        stroke={ink}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={thickness}
+      >
+        <path d={path} className={animated ? "ck-sketch-drawon" : undefined} style={animated ? { ["--ck-sketch-len" as never]: len + 30 } : undefined} />
+        <path d={`M ${x2} ${y2} L ${ax1} ${ay1}`} />
+        <path d={`M ${x2} ${y2} L ${ax2} ${ay2}`} />
+      </g>
+    </svg>
+  );
+}

package/src/sketch/RoughBox.tsx

@@ -0,0 +1,73 @@
+import type { CSSProperties, ReactNode } from "react";
+
+// A drawn rectangle — used to wrap any content in a "sketched"
+// container. CSS-only: asymmetric border-radius + 2px ink stroke
+// + offset second stroke shadow. Pair with `tilt` and an optional
+// `fill` (transparent | hatch | marker color) for emphasis.
+//
+// Why a primitive: this is the canonical "drawn rectangle" pattern
+// — buttons, cards, sticky notes, tool tips all inherit from it.
+// Wrapping it once keeps the wobble math + tilt presets DRY.
+
+export interface RoughBoxProps {
+  children?: ReactNode;
+  // Tilt in degrees. Defaults to a small -1.
+  tilt?: number;
+  // Fill style. Defaults to "paper". "hatch" lays down diagonal
+  // marker strokes; "marker" floods a translucent marker color.
+  fill?: "paper" | "hatch" | "marker" | "transparent";
+  // Marker color when fill="hatch" or fill="marker". Accepts any
+  // CSS color, including the --ck-sketch-* vars.
+  ink?: string;
+  // Override radius. Defaults to a chrome-aware asymmetric value.
+  radius?: string;
+  // Drawing thickness, in px. Defaults to 2.
+  stroke?: number;
+  // Padding inside the box. Defaults to 16.
+  padding?: number | string;
+  // Set to true to skip the offset second-stroke shadow.
+  flat?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function RoughBox({
+  children,
+  tilt = -1,
+  fill = "paper",
+  ink = "var(--ck-sketch-yellow, #F2C94C)",
+  radius = "10px 14px 12px 16px / 14px 10px 16px 12px",
+  stroke = 2,
+  padding = 16,
+  flat = false,
+  className,
+  style,
+}: RoughBoxProps) {
+  const inkColor = "var(--ck-text-primary, #1A1A1A)";
+  let background: string;
+  if (fill === "hatch") {
+    background = `repeating-linear-gradient(45deg, ${ink} 0 3px, transparent 3px 9px), var(--ck-bg-surface, #FFFEF9)`;
+  } else if (fill === "marker") {
+    background = `color-mix(in oklab, ${ink} 22%, transparent), var(--ck-bg-surface, #FFFEF9)`;
+  } else if (fill === "transparent") {
+    background = "transparent";
+  } else {
+    background = "var(--ck-bg-surface, #FFFEF9)";
+  }
+  return (
+    <div
+      className={className}
+      style={{
+        background,
+        border: `${stroke}px solid ${inkColor}`,
+        borderRadius: radius,
+        boxShadow: flat ? "none" : `3px 4px 0 ${inkColor}`,
+        padding,
+        transform: `rotate(${tilt}deg)`,
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+}