@openvidstudio/styles 0.0.0-stage → 1.4.0

package/src/narrator.ts

@@ -0,0 +1,243 @@
+import { drawSprite, frameAt, makeSprite, type DrawSpriteOptions, type Sprite } from "./sprites";
+import { ACCENTS } from "./tokens";
+
+export type Pose = "idle" | "talk" | "point" | "think" | "celebrate";
+export const POSES: readonly Pose[] = ["idle", "talk", "point", "think", "celebrate"];
+
+export const NARRATOR_WIDTH = 16;
+export const NARRATOR_HEIGHT = 23;
+
+/** The narrator's base palette. "b" (shirt) and "a" (sparkle) take the lesson's accent. */
+export function narratorPalette(accent: string = ACCENTS.math): Record<string, string> {
+  return {
+    o: "#14172B",
+    h: "#5B4A8A",
+    s: "#FFD2A8",
+    e: "#14172B",
+    m: "#D6455D",
+    b: accent,
+    w: "#FFFFFF",
+    p: "#3F4B73",
+    a: accent,
+  };
+}
+
+class Grid {
+  private rows: string[][];
+  constructor(
+    readonly w: number,
+    readonly h: number,
+  ) {
+    this.rows = Array.from({ length: h }, () => Array<string>(w).fill("."));
+  }
+  set(x: number, y: number, text: string): void {
+    for (let i = 0; i < text.length; i++) {
+      const px = x + i;
+      if (px >= 0 && px < this.w && y >= 0 && y < this.h) this.rows[y][px] = text[i];
+    }
+  }
+  lines(): string[] {
+    return this.rows.map((r) => r.join(""));
+  }
+}
+
+type Mouth = "closed" | "open" | "half" | "grin";
+
+interface Spec {
+  pose: Pose;
+  /** Rows the figure sits below the top of the sprite (the headroom is for jumps and the thought dots). */
+  oy: number;
+  blink?: boolean;
+  mouth?: Mouth;
+  /** point: how far the arm reaches. think: dots shown. celebrate: sparkle phase. */
+  k?: number;
+}
+
+function build(spec: Spec): string[] {
+  const g = new Grid(NARRATOR_WIDTH, NARRATOR_HEIGHT);
+  const y = spec.oy;
+  const eyes = spec.blink || spec.pose === "celebrate" ? "ssoossooss" : "sseessseess";
+  // head, 9 rows
+  g.set(0, y + 0, "....oooooooo....");
+  g.set(0, y + 1, "...ohhhhhhhho...");
+  g.set(0, y + 2, "..ohhhhhhhhhho..");
+  g.set(0, y + 3, "..o" + "hssssssssh" + "o..");
+  g.set(0, y + 4, "..o" + eyes + "o..");
+  g.set(0, y + 5, "..o" + "ssssssssss" + "o..");
+  const mouths: Record<Mouth, [string, string]> = {
+    closed: ["ssssmmssss", "ssssssssss"],
+    half: ["ssssmmssss", "sssssmssss"],
+    open: ["ssssmmssss", "ssssmmssss"],
+    grin: ["sssmmmmsss", "ssssssssss"],
+  };
+  const [mouth1, mouth2] = mouths[spec.mouth ?? "closed"];
+  g.set(0, y + 6, "..o" + mouth1 + "o..");
+  g.set(0, y + 7, "..o" + mouth2 + "o..");
+  g.set(0, y + 8, "...oooooooooo...");
+
+  // torso
+  g.set(0, y + 9, "....oooooooo....");
+  for (let r = 10; r <= 14; r++) g.set(0, y + r, r === 12 ? "....obbwwbbo...." : "....obbbbbbo....");
+  g.set(0, y + 15, "....oooooooo....");
+
+  // legs and shoes
+  g.set(0, y + 16, "....oppppppo....");
+  g.set(0, y + 17, "....opppoppo....");
+  g.set(0, y + 18, "....oppo.ppo....");
+  g.set(0, y + 19, "...owwo..owwo...");
+  g.set(0, y + 20, "...oooo..oooo...");
+
+  const armDown = (left: boolean): void => {
+    for (let r = 10; r <= 14; r++) {
+      if (left) {
+        g.set(2, y + r, "os");
+      } else {
+        g.set(12, y + r, "so");
+      }
+    }
+    if (left) g.set(2, y + 15, "oo");
+    else g.set(12, y + 15, "oo");
+  };
+
+  switch (spec.pose) {
+    case "idle":
+    case "talk":
+      armDown(true);
+      armDown(false);
+      break;
+    case "point": {
+      armDown(true);
+      const reach = spec.k ?? 0;
+      g.set(12, y + 9, "oooo");
+      g.set(12, y + 10, "ssss");
+      g.set(12, y + 11, "oooo");
+      if (reach === 0) {
+        g.set(15, y + 9, ".");
+        g.set(15, y + 10, ".");
+        g.set(15, y + 11, ".");
+        g.set(14, y + 9, "o");
+        g.set(14, y + 10, "o");
+        g.set(14, y + 11, "o");
+      }
+      break;
+    }
+    case "think": {
+      armDown(true);
+      g.set(12, y + 8, "ss");
+      g.set(14, y + 8, "o");
+      g.set(12, y + 9, "ss");
+      g.set(14, y + 9, "o");
+      for (let r = 10; r <= 12; r++) g.set(12, y + r, "so");
+      const dots = spec.k ?? 0;
+      const at = [11, 13, 15];
+      for (let i = 0; i < dots && i < 3; i++) g.set(at[i], 0, "w");
+      break;
+    }
+    case "celebrate": {
+      for (let r = 3; r <= 10; r++) {
+        g.set(0, y + r, "os");
+        g.set(14, y + r, "so");
+      }
+      g.set(2, y + 9, "s");
+      g.set(2, y + 10, "s");
+      g.set(13, y + 9, "s");
+      g.set(13, y + 10, "s");
+      g.set(0, y + 2, "ss");
+      g.set(14, y + 2, "ss");
+      const phase = spec.k ?? 0;
+      if (phase === 0) {
+        g.set(0, 0, "a");
+        g.set(15, 0, "a");
+      } else {
+        g.set(2, 0, "a");
+        g.set(13, 0, "a");
+      }
+      break;
+    }
+  }
+  return g.lines();
+}
+
+const OY = 2;
+
+const FRAMES: Record<Pose, { frames: Spec[]; fps: number }> = {
+  idle: {
+    fps: 4,
+    frames: [
+      { pose: "idle", oy: OY },
+      { pose: "idle", oy: OY },
+      { pose: "idle", oy: OY },
+      { pose: "idle", oy: OY },
+      { pose: "idle", oy: OY },
+      { pose: "idle", oy: OY, blink: true },
+      { pose: "idle", oy: OY },
+      { pose: "idle", oy: OY },
+    ],
+  },
+  talk: {
+    fps: 8,
+    frames: [
+      { pose: "talk", oy: OY, mouth: "half" },
+      { pose: "talk", oy: OY, mouth: "open" },
+      { pose: "talk", oy: OY, mouth: "closed" },
+      { pose: "talk", oy: OY, mouth: "open" },
+    ],
+  },
+  point: {
+    fps: 3,
+    frames: [
+      { pose: "point", oy: OY, mouth: "half", k: 0 },
+      { pose: "point", oy: OY, mouth: "closed", k: 1 },
+    ],
+  },
+  think: {
+    fps: 2,
+    frames: [
+      { pose: "think", oy: OY, k: 0 },
+      { pose: "think", oy: OY, k: 1 },
+      { pose: "think", oy: OY, k: 2 },
+      { pose: "think", oy: OY, k: 3 },
+    ],
+  },
+  celebrate: {
+    fps: 5,
+    frames: [
+      { pose: "celebrate", oy: 1, mouth: "grin", k: 0 },
+      { pose: "celebrate", oy: 0, mouth: "grin", k: 1 },
+    ],
+  },
+};
+
+const cache = new Map<string, Sprite>();
+
+/** The narrator sprite for a pose, in an accent colour. Sprites are cached per pose and accent. */
+export function narratorSprite(pose: Pose, accent: string = ACCENTS.math): Sprite {
+  const key = `${pose}|${accent}`;
+  let s = cache.get(key);
+  if (!s) {
+    const def = FRAMES[pose];
+    s = makeSprite(narratorPalette(accent), def.frames.map(build), def.fps);
+    cache.set(key, s);
+  }
+  return s;
+}
+
+/** Which animation frame the pose shows at time t (seconds). Pure in t. */
+export function narratorFrame(pose: Pose, t: number): number {
+  return frameAt(narratorSprite(pose), t);
+}
+
+/** Draws the narrator in a pose at time t. (x, y) is the sprite's top-left. */
+export function drawNarrator(
+  ctx: CanvasRenderingContext2D,
+  pose: Pose,
+  x: number,
+  y: number,
+  scale: number,
+  t: number,
+  accent: string = ACCENTS.math,
+  opts: DrawSpriteOptions = {},
+): void {
+  const sprite = narratorSprite(pose, accent);
+  drawSprite(ctx, sprite, x, y, scale, frameAt(sprite, t), opts);
+}

package/src/props.ts

@@ -0,0 +1,121 @@
+import { drawSprite, frameAt, makeSprite, type DrawSpriteOptions, type Sprite } from "./sprites";
+
+const BALL = makeSprite(
+  { o: "#14172B", r: "#FF4D5E", w: "#FFFFFF" },
+  [
+    ["..oooo..", ".orrrro.", "orwrrrro", "orrrrrro", "orrrrrro", "orrrrrro", ".orrrro.", "..oooo.."],
+    ["..oooo..", ".orrrro.", "orrrrrro", "orrwrrro", "orrrrrro", "orrrrrro", ".orrrro.", "..oooo.."],
+  ],
+  4,
+);
+
+const RULER = makeSprite({ o: "#14172B", y: "#FFD36B", t: "#14172B" }, [
+  [
+    "oooooooooooooooo",
+    "otyytyytyytyytyo",
+    "oyyyyyyyyyyyyyyo",
+    "oyyyyyyyyyyyyyyo",
+    "oooooooooooooooo",
+  ],
+]);
+
+const BATTERY = makeSprite(
+  { o: "#14172B", w: "#E7ECF7", k: "#3A3F55", g: "#7CFFB2" },
+  [
+    ["..oooo..", "..owwo..", "oooooooo", "okkkkkko", "okggggko", "okggggko", "okkkkkko", "okggggko", "okggggko", "okkkkkko", "okkkkkko", "oooooooo"],
+    ["..oooo..", "..owwo..", "oooooooo", "okkkkkko", "okggggko", "okggggko", "okkkkkko", "okggggko", "okkkkkko", "okkkkkko", "okkkkkko", "oooooooo"],
+  ],
+  2,
+);
+
+const CABLE = makeSprite({ o: "#14172B", w: "#E7ECF7", c: "#FFB347" }, [
+  [
+    "ooo.............",
+    "owwoo...........",
+    "ooooccc.........",
+    ".....cccc.......",
+    ".......cccc.....",
+    ".........ccccooo",
+    "..........ooowwo",
+    "...........oooo.",
+  ],
+]);
+
+const BRIDGE = makeSprite({ o: "#14172B", y: "#C98B4B" }, [
+  [
+    "........................",
+    "oooooooooooooooooooooooo",
+    "oyyyyyyyyyyyyyyyyyyyyyyo",
+    "oooooooooooooooooooooooo",
+    "o..o..o..o..o..o..o..o..",
+    "o.o.o.o.o.o.o.o.o.o.o.o.",
+    "oo..oo..oo..oo..oo..oo..",
+    "oooooooooooooooooooooooo",
+  ],
+]);
+
+const BAT = makeSprite({ o: "#14172B", k: "#3A3F55", y: "#D9A066" }, [
+  [
+    "..oo..",
+    ".okko.",
+    ".okko.",
+    ".okko.",
+    ".okko.",
+    ".okko.",
+    ".okko.",
+    ".okko.",
+    ".okko.",
+    ".oyyo.",
+    "oyyyyo",
+    "oyyyyo",
+    "oyyyyo",
+    "oyyyyo",
+    "oyyyyo",
+    ".oooo.",
+  ],
+]);
+
+const registry = new Map<string, Sprite>([
+  ["ball", BALL],
+  ["ruler", RULER],
+  ["battery", BATTERY],
+  ["cable", CABLE],
+  ["bridge", BRIDGE],
+  ["bat", BAT],
+]);
+
+/** Names of the built-in props, in a stable order. */
+export const BUILTIN_PROPS = ["ball", "ruler", "battery", "cable", "bridge", "bat"] as const;
+
+/**
+ * Adds a prop a lesson needs (a beaker, a magnet, a cell). Build it with makeSprite. A name that
+ * already exists is refused unless `overwrite` is set, so a lesson cannot silently change a built-in.
+ */
+export function registerProp(name: string, sprite: Sprite, overwrite = false): void {
+  if (registry.has(name) && !overwrite) throw new Error(`A prop named "${name}" already exists; pass overwrite to replace it.`);
+  registry.set(name, sprite);
+}
+
+export function getProp(name: string): Sprite {
+  const s = registry.get(name);
+  if (!s) throw new Error(`No prop named "${name}". Known: ${propNames().join(", ")}.`);
+  return s;
+}
+
+export function propNames(): string[] {
+  return [...registry.keys()];
+}
+
+/** Draws a prop by name; animated props (ball, battery) pick their frame from t. */
+export function drawProp(
+  ctx: CanvasRenderingContext2D,
+  name: string,
+  x: number,
+  y: number,
+  scale: number,
+  t = 0,
+  opts: DrawSpriteOptions = {},
+): void {
+  const sprite = getProp(name);
+  drawSprite(ctx, sprite, x, y, scale, frameAt(sprite, t), opts);
+}

package/src/rng.ts

@@ -0,0 +1,31 @@
+/**
+ * A small seeded PRNG (mulberry32). Every random-looking thing in this package draws from one of
+ * these, never from the platform's global generator, so a frame is a pure function of its inputs.
+ */
+export interface Rng {
+  /** Next float in [0, 1). */
+  next(): number;
+  /** Float in [min, max). */
+  range(min: number, max: number): number;
+  /** Integer in [min, max], both ends included. */
+  int(min: number, max: number): number;
+  /** One element of a non-empty array. */
+  pick<T>(items: readonly T[]): T;
+}
+
+export function createRng(seed: number): Rng {
+  let a = seed >>> 0;
+  const next = (): number => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  return {
+    next,
+    range: (min, max) => min + next() * (max - min),
+    int: (min, max) => min + Math.floor(next() * (max - min + 1)),
+    pick: (items) => items[Math.floor(next() * items.length)],
+  };
+}

package/src/sprites.ts

@@ -0,0 +1,90 @@
+/**
+ * Palette-indexed string-grid sprites. Each frame is an array of equal-width strings; every
+ * character is a palette key, and "." is transparent. Drawing is integer-scale fillRect with
+ * smoothing off, so a pixel is exactly scale x scale device pixels with no blending.
+ */
+export interface Sprite {
+  readonly width: number;
+  readonly height: number;
+  /** Palette key (one character) to a CSS colour. */
+  readonly palette: Readonly<Record<string, string>>;
+  readonly frames: readonly (readonly string[])[];
+  /** Frames per second when played by time (see frameAt). */
+  readonly fps: number;
+}
+
+export function makeSprite(
+  palette: Record<string, string>,
+  frames: readonly (readonly string[])[],
+  fps = 6,
+): Sprite {
+  if (frames.length === 0) throw new Error("A sprite needs at least one frame.");
+  const height = frames[0].length;
+  const width = frames[0][0]?.length ?? 0;
+  frames.forEach((frame, f) => {
+    if (frame.length !== height) throw new Error(`Sprite frame ${f} has ${frame.length} rows; expected ${height}.`);
+    frame.forEach((row, r) => {
+      if (row.length !== width) throw new Error(`Sprite frame ${f} row ${r} is ${row.length} wide; expected ${width}.`);
+      for (const ch of row) {
+        if (ch !== "." && !(ch in palette)) throw new Error(`Sprite frame ${f} row ${r} uses "${ch}", which is not in the palette.`);
+      }
+    });
+  });
+  return { width, height, palette, frames, fps };
+}
+
+/** Which frame plays at time t (seconds): a pure function of t. */
+export function frameAt(sprite: Sprite, t: number): number {
+  const n = sprite.frames.length;
+  const i = Math.floor(Math.max(0, t) * sprite.fps) % n;
+  return i;
+}
+
+export interface DrawSpriteOptions {
+  /** Draw every opaque pixel in this one colour (a silhouette, for shadows). */
+  tint?: string;
+  /** Mirror left to right. */
+  flipX?: boolean;
+  /** Replace palette colours by key for this draw. */
+  palette?: Record<string, string>;
+}
+
+/**
+ * Draws one frame with its top-left at (x, y). The scale is rounded to a whole number of at
+ * least 1 and the position to whole pixels, so every sprite pixel stays a crisp block.
+ */
+export function drawSprite(
+  ctx: CanvasRenderingContext2D,
+  sprite: Sprite,
+  x: number,
+  y: number,
+  scale = 1,
+  frame = 0,
+  opts: DrawSpriteOptions = {},
+): void {
+  const s = Math.max(1, Math.round(scale));
+  const ox = Math.round(x);
+  const oy = Math.round(y);
+  const rows = sprite.frames[((frame % sprite.frames.length) + sprite.frames.length) % sprite.frames.length];
+  ctx.save();
+  ctx.imageSmoothingEnabled = false;
+  ctx.globalCompositeOperation = "source-over";
+  for (let r = 0; r < rows.length; r++) {
+    const row = rows[r];
+    let c = 0;
+    while (c < row.length) {
+      const ch = row[c];
+      if (ch === ".") {
+        c++;
+        continue;
+      }
+      let end = c + 1;
+      while (end < row.length && row[end] === ch) end++;
+      ctx.fillStyle = opts.tint ?? opts.palette?.[ch] ?? sprite.palette[ch];
+      const px = opts.flipX ? sprite.width - end : c;
+      ctx.fillRect(ox + px * s, oy + r * s, (end - c) * s, s);
+      c = end;
+    }
+  }
+  ctx.restore();
+}

package/src/tokens.ts

@@ -0,0 +1,31 @@
+export type Subject = "math" | "physics" | "cs" | "chemistry" | "biology";
+
+/** One accent per subject. */
+export const ACCENTS: Record<Subject, string> = {
+  math: "#5CC8FF",
+  physics: "#FFB347",
+  cs: "#B58CFF",
+  chemistry: "#FF4D5E",
+  biology: "#7CFFB2",
+};
+
+export const SUBJECTS = Object.keys(ACCENTS) as Subject[];
+
+/** The flat dark ground the kit is designed against. */
+export const VOID = "#0B0D14";
+
+export function accentFor(subject: Subject): string {
+  return ACCENTS[subject];
+}
+
+/** "#RRGGBB" to [r, g, b]. */
+export function hexToRgb(hex: string): [number, number, number] {
+  const n = parseInt(hex.slice(1), 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+/** An "rgba(...)" string for a hex colour at an alpha. */
+export function withAlpha(hex: string, alpha: number): string {
+  const [r, g, b] = hexToRgb(hex);
+  return `rgba(${r},${g},${b},${Math.max(0, Math.min(1, alpha))})`;
+}