@wodzik/cubecore 0.1.0

package/element/sequence.js

@@ -0,0 +1,254 @@
+/**
+ * CubeSequenceElement — what <cube-scramble> and <cube-alg-practice> share:
+ * a list of moves followed on a smart cube (core SequenceTracker under the
+ * hood), with the slip / undo line, a status message, controls, events and
+ * one styling vocabulary. Not registered on its own.
+ *
+ * Three levels of customising, like <cube-player>:
+ *   1. CSS variables (on the element or any ancestor):
+ *        --cc-seq-font, --cc-seq-size, --cc-seq-gap           text
+ *        --cc-seq-done, --cc-seq-current, --cc-seq-current-bg, --cc-seq-partial,
+ *        --cc-seq-todo, --cc-seq-hidden (dots), --cc-seq-undo,
+ *        --cc-seq-wrong-way (the move due, turned the wrong way)   move colours
+ *        --cc-accent, --cc-control-bg, --cc-control-radius      controls
+ *   2. ::part(): container, moves, move, move-done / -current / -partial / -todo /
+ *      -hidden, undo, undo-label, undo-move, message, controls, button (+ button-<name>),
+ *      and each element's own (scramble: input, error).
+ *   3. Replace pieces: children with slot="undo", slot="message" or
+ *      slot="controls" take those places (controls="none" hides the default
+ *      controls); `headless` hides the whole built-in view — build yours
+ *      from the `progress` event (tokens with text / status / visibility,
+ *      undo, needsReset, complete, …) and call the element's methods.
+ *
+ * Arrows: with `arrows` set (the element following a cube — attached, or
+ * fed with push()) and a player (`player="id"` of a <cube-player>,
+ * or the `player` property), the 3D cube shows the next turn — one arrow per
+ * turning layer (two for a wide r), as many heads as quarter turns, in
+ * --cc-arrow; after a slip the undo move in --cc-arrow-undo, or in
+ * --cc-arrow-wrong-way when the right face went the wrong way.
+ * `arrow-shape="circle"` for arcs instead of ribbons along the faces.
+ *
+ * After a slip the moves give way to the way back: the undo moves in their
+ * place (--cc-seq-undo), until the cube is back on track —
+ * `undo-display="below"` keeps the moves and shows the undo line under them.
+ *
+ * Events: progress (detail: the progress), complete.
+ */
+import { IDENTITY_FRAME, formatMove, solvedState } from "../core/index.js";
+import { ElementBase } from "./base.js";
+export const SEQUENCE_STYLES = /* css */ `
+:host {
+  --cc-seq-font: ui-monospace, "SF Mono", Menlo, monospace;
+  --cc-seq-size: 22px;
+  --cc-seq-gap: 0.35em;
+  --cc-seq-done: color-mix(in srgb, currentColor 35%, transparent);
+  --cc-seq-current: currentColor;
+  --cc-seq-current-bg: color-mix(in srgb, var(--cc-accent) 24%, transparent);
+  --cc-seq-partial: var(--cc-accent);
+  --cc-seq-todo: color-mix(in srgb, currentColor 82%, transparent);
+  --cc-seq-hidden: color-mix(in srgb, currentColor 45%, transparent);
+  --cc-seq-undo: #ff5a5a;
+  --cc-seq-wrong-way: #ff9a1f;
+  --cc-seq-decoration: color-mix(in srgb, currentColor 70%, transparent);
+  --cc-arrow: #2f8bff;
+  --cc-arrow-undo: #ff4545;
+  --cc-arrow-wrong-way: #ff9a1f;
+  --cc-accent: #4f8cff;
+  --cc-control-bg: color-mix(in srgb, currentColor 8%, transparent);
+  --cc-control-bg-hover: color-mix(in srgb, currentColor 15%, transparent);
+  --cc-control-radius: 8px;
+  display: block;
+}
+:host([headless]) .container { display: none; }
+.group { display: inline-flex; align-items: baseline; }
+.decoration { color: var(--cc-seq-decoration); }
+.container { display: flex; flex-direction: column; gap: 0.5em; }
+.container.slip .moves { display: none; }
+.container.slip .undo { font-size: var(--cc-seq-size); line-height: 1.5; }
+.moves { display: flex; flex-wrap: wrap; gap: 0.1em var(--cc-seq-gap); font: 600 var(--cc-seq-size) / 1.5 var(--cc-seq-font); }
+.move { padding: 0 0.18em; border-radius: 0.25em; transition: color 0.15s ease, background 0.15s ease; }
+.done { color: var(--cc-seq-done); }
+.current { color: var(--cc-seq-current); background: var(--cc-seq-current-bg); }
+.partial { color: var(--cc-seq-partial); background: var(--cc-seq-current-bg); }
+.wrong-way { color: var(--cc-seq-wrong-way); background: var(--cc-seq-current-bg); }
+.todo { color: var(--cc-seq-todo); }
+.hidden { color: var(--cc-seq-hidden); }
+.undo { display: none; color: var(--cc-seq-undo); gap: var(--cc-seq-gap); flex-wrap: wrap; align-items: baseline; font: 600 calc(var(--cc-seq-size) * 0.85) / 1.4 var(--cc-seq-font); }
+.undo.on { display: flex; }
+.undo-label { font: 600 0.65em/1 system-ui, sans-serif; text-transform: uppercase; letter-spacing: 0.06em; margin-right: 0.3em; }
+.message { display: none; font: 500 13px/1.4 system-ui, sans-serif; opacity: 0.85; }
+.message.on { display: block; }
+.controls { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
+.controls:empty { display: none; }
+:host([controls="none"]) .controls { display: none; }
+button {
+  border: 0; border-radius: var(--cc-control-radius);
+  background: var(--cc-control-bg); color: inherit;
+  padding: 6px 11px; font: 600 12px/1 system-ui, sans-serif; cursor: pointer;
+}
+button:hover { background: var(--cc-control-bg-hover); }
+button:focus-visible, input:focus-visible { outline: 2px solid var(--cc-accent); outline-offset: 2px; }
+button[aria-pressed="true"] { background: color-mix(in srgb, var(--cc-accent) 25%, transparent); }
+`;
+export class CubeSequenceElement extends ElementBase {
+    root;
+    source = null;
+    off = null;
+    messagesBase = { undo: "Undo", reset: "Too far off — solve the cube and start again", complete: "" };
+    completed = false;
+    _player = null;
+    /** How the cube is held when the sequence starts (see `frame`). */
+    startFrame = IDENTITY_FRAME;
+    static observedAttributes = ["arrows", "player", "arrow-shape", "undo-display"];
+    attributeChangedCallback() {
+        this.update();
+    }
+    constructor(extraStyles = "", controlsHtml = "") {
+        super();
+        this.root = this.attachShadow({ mode: "open" });
+        this.root.innerHTML = `<style>${SEQUENCE_STYLES}${extraStyles}</style>
+      <div class="container" part="container">
+        <div class="moves" part="moves"></div>
+        <slot name="undo"><div class="undo" part="undo"><span class="undo-label" part="undo-label"></span><span class="undo-moves"></span></div></slot>
+        <slot name="message"><div class="message" part="message" role="status"></div></slot>
+        <slot name="controls"><div class="controls" part="controls">${controlsHtml}</div></slot>
+      </div>`;
+        this.root.addEventListener("click", (e) => {
+            const action = e.target.closest("[data-action]")?.dataset.action;
+            if (action)
+                this.onAction(action);
+        });
+    }
+    /** Extra message (e.g. stats) when nothing else is said. */
+    extraMessage() {
+        return "";
+    }
+    onAction(_action) { }
+    // ─── shared API ───
+    /** Follow a smart cube from its current state. Returns detach. */
+    attach(source) {
+        this.detach();
+        this.source = source;
+        this.off = source.on("move", (e) => this.push(e.move, e.time));
+        this.reset();
+        return () => this.detach();
+    }
+    detach() {
+        this.arrowTarget()?.showTurnArrows(null, {}, this);
+        this.off?.();
+        this.off = null;
+        this.source = null;
+    }
+    /**
+     * How the cube is held when the sequence starts (default: its own U on top,
+     * F in front) — for an algorithm right after one with a net rotation.
+     * Setting it starts again.
+     */
+    get frame() {
+        return this.startFrame;
+    }
+    set frame(f) {
+        this.startFrame = f ?? IDENTITY_FRAME;
+        this.reset();
+    }
+    /** Start again from `start` (default: the attached cube's state, else solved). */
+    reset(start) {
+        this.completed = false;
+        this.startTracking(start ?? this.source?.state ?? solvedState());
+        this.update();
+    }
+    /** A face turn from the cube (called for you when attached). Once complete, further turns are
+     * ignored (the solve / next attempt has started) until a new sequence or `reset()`. */
+    push(move, time = performance.now()) {
+        if (this.completed)
+            return;
+        const p = this.track(move, time);
+        this.update();
+        if (p.complete && !this.completed) {
+            this.completed = true;
+            this.dispatchEvent(new CustomEvent("complete", { detail: p }));
+        }
+    }
+    /** Player for the arrows (else the `player` attribute's id). */
+    get player() {
+        return this.arrowTarget();
+    }
+    set player(p) {
+        this.arrowTarget()?.showTurnArrows(null, {}, this);
+        this._player = p;
+        this.update();
+    }
+    arrowTarget() {
+        if (this._player)
+            return this._player;
+        const id = this.getAttribute("player");
+        const el = id ? this.getRootNode().getElementById?.(id) : null;
+        return el && "showTurnArrows" in el ? el : null;
+    }
+    /** Draw the arrows again — e.g. after changing --cc-arrow* (CSS changes don't notify the element). */
+    refreshArrows() {
+        this.syncArrows();
+    }
+    syncArrows() {
+        const target = this.arrowTarget();
+        if (!target)
+            return;
+        // The page opts in with `arrows` (a cube followed by attach() or push()).
+        const turn = this.hasAttribute("arrows") ? this.nextTurn() : null;
+        if (!turn)
+            return target.showTurnArrows(null, {}, this);
+        const css = getComputedStyle(this);
+        const color = css.getPropertyValue(turn.kind === "next" ? "--cc-arrow" : `--cc-arrow-${turn.kind}`).trim();
+        const shape = this.getAttribute("arrow-shape") === "circle" ? "circle" : "box";
+        target.showTurnArrows(turn.arrows, { color: color || undefined, shape }, this);
+    }
+    get messages() {
+        return { ...this.messagesBase };
+    }
+    set messages(m) {
+        this.setMessages(m);
+    }
+    setMessages(m) {
+        this.messagesBase = { ...this.messagesBase, ...m };
+        this.update();
+    }
+    /** Text around written move `index` (none here; <cube-alg-practice> has trigger groups). */
+    decorationOf(_index) {
+        return undefined;
+    }
+    // ─── rendering ───
+    update() {
+        const p = this.progress;
+        const deco = (text) => (text ? `<span class="decoration" part="decoration">${escapeHtml(text)}</span>` : "");
+        this.root.querySelector(".moves").innerHTML = this.tokens()
+            .map((t, i) => {
+            const cls = t.visible ? t.status : `${t.status} hidden`;
+            const parts = t.visible ? `move move-${t.status}` : `move move-${t.status} move-hidden`;
+            const d = this.decorationOf(i);
+            const move = `<span class="move ${cls}" part="${parts}">${t.visible ? escapeHtml(t.text) : "•"}</span>`;
+            return d ? `<span class="group">${deco(d.prefix)}${move}${deco(d.suffix)}</span>` : move;
+        })
+            .join("");
+        const showUndo = !!p && p.undo.length > 0 && !p.needsReset;
+        // A real slip: the moves give way to the way back. The move due just turned the wrong way: it turns orange instead.
+        const slip = showUndo && !p.wrongWay;
+        this.root.querySelector(".container")?.classList.toggle("slip", slip && this.getAttribute("undo-display") !== "below");
+        this.root.querySelector(".undo")?.classList.toggle("on", slip);
+        const label = this.root.querySelector(".undo-label");
+        if (label)
+            label.textContent = this.messagesBase.undo;
+        const undoMoves = this.root.querySelector(".undo-moves");
+        if (undoMoves)
+            undoMoves.innerHTML = showUndo ? p.undo.map((m) => `<span class="move" part="undo-move">${formatMove(m)}</span>`).join(" ") : "";
+        const message = this.root.querySelector(".message");
+        if (message) {
+            const text = p?.needsReset ? this.messagesBase.reset : p?.complete && this.messagesBase.complete ? this.messagesBase.complete : this.extraMessage();
+            message.textContent = text;
+            message.classList.toggle("on", !!text);
+        }
+        this.syncArrows();
+        if (p)
+            this.dispatchEvent(new CustomEvent("progress", { detail: { ...p, shown: this.tokens() } }));
+    }
+}
+export const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");

package/element/styles.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Default look of <cube-player>. Everything is themable from outside:
+ *
+ * - CSS custom properties on the element (or any ancestor) — quick theming:
+ *     --cc-accent            play button, progress fill, focus ring
+ *     --cc-control-bg        button background        --cc-control-bg-hover
+ *     --cc-control-fg        button icon colour       --cc-control-radius
+ *     --cc-button-size       button height/width      --cc-controls-gap
+ *     --cc-progress-height   bar thickness            --cc-progress-track / --cc-progress-fill
+ *     --cc-marker            stage marker colour      --cc-thumb-size
+ *     --cc-font              time / speed text
+ * - ::part() for anything else: stage, flat (the 2D picture), progress, progress-track,
+ *   progress-fill, progress-thumb, progress-marker, segment (+ segment-<id>),
+ *   segment-played, segment-recognition, segment-labels, segment-label
+ *   (+ segment-label-<id>), tooltip, tooltip-text, controls, buttons, button,
+ *   button-start, button-back, button-play, button-forward, button-end,
+ *   button-speed, time.
+ * - Replace the controls entirely: put your own element in slot="controls"
+ *   (or set controls="none") and drive the player's API.
+ *
+ * Colours derive from `currentColor`, so the defaults fit light and dark pages.
+ */
+export declare const STYLES = "\n:host {\n  --cc-accent: #4f8cff;\n  --cc-control-bg: color-mix(in srgb, currentColor 8%, transparent);\n  --cc-control-bg-hover: color-mix(in srgb, currentColor 15%, transparent);\n  --cc-control-fg: currentColor;\n  --cc-control-radius: 10px;\n  --cc-button-size: 34px;\n  --cc-controls-gap: 5px;\n  --cc-progress-height: 6px;\n  --cc-progress-track: color-mix(in srgb, currentColor 14%, transparent);\n  --cc-progress-fill: var(--cc-accent);\n  --cc-marker: color-mix(in srgb, currentColor 55%, transparent);\n  --cc-thumb-size: 14px;\n  --cc-font: ui-monospace, \"SF Mono\", Menlo, monospace;\n  /* sections of the progress bar */\n  --cc-segment-1: #4f8cff;\n  --cc-segment-2: #22c55e;\n  --cc-segment-3: #f59e0b;\n  --cc-segment-4: #ef4444;\n  --cc-segment-5: #a855f7;\n  --cc-segment-6: #14b8a6;\n  --cc-segment-7: #ec4899;\n  --cc-segment-8: #eab308;\n  --cc-segment-height: calc(var(--cc-progress-height) + 2px);\n  --cc-segment-gap: 2px;\n  --cc-segment-unplayed: 30%;\n  /* popup: inverted page colours by default (text colour as background) */\n  --cc-tooltip-bg: color-mix(in srgb, currentColor 92%, transparent);\n  --cc-tooltip-fg: Canvas;\n  display: flex;\n  flex-direction: column;\n  gap: 10px;\n  min-width: 200px;\n  min-height: 200px;\n  outline: none;\n  container-type: inline-size;\n}\n:host([hidden]) { display: none; }\n.stage { position: relative; flex: 1; min-height: 0; }\n.flat { position: absolute; inset: 0; display: grid; place-items: center; }\n.flat[hidden] { display: none; }\n.flat svg { width: 100%; height: 100%; }\n\n/* \u2500\u2500\u2500 progress bar \u2500\u2500\u2500 */\n.progress { display: none; padding: 6px 2px; cursor: pointer; touch-action: none; }\n:host([progress]) .progress { display: block; }\n.track {\n  position: relative;\n  height: var(--cc-progress-height);\n  border-radius: 999px;\n  background: var(--cc-progress-track);\n}\n.fill {\n  position: absolute; inset: 0 auto 0 0;\n  width: 0;\n  border-radius: inherit;\n  background: var(--cc-progress-fill);\n}\n.thumb {\n  position: absolute; top: 50%; left: 0;\n  width: var(--cc-thumb-size); height: var(--cc-thumb-size);\n  border-radius: 50%;\n  background: var(--cc-progress-fill);\n  box-shadow: 0 0 0 3px color-mix(in srgb, var(--cc-progress-fill) 25%, transparent);\n  transform: translate(-50%, -50%) scale(0.85);\n  transition: transform 0.12s ease;\n}\n.progress:hover .thumb, .progress.dragging .thumb { transform: translate(-50%, -50%) scale(1); }\n/* Sections: coloured parts of the bar, dim until played, recognition hatched. */\n.progress { position: relative; }\n.progress.has-segments .fill { display: none; }\n.segments { position: absolute; inset: 0; }\n.segment {\n  position: absolute; top: 50%;\n  height: var(--cc-segment-height);\n  transform: translateY(-50%);\n  overflow: hidden;\n  background: color-mix(in srgb, var(--seg) var(--cc-segment-unplayed), transparent);\n  clip-path: inset(0 calc(var(--cc-segment-gap) / 2) 0 calc(var(--cc-segment-gap) / 2) round 999px);\n}\n.segment .played { position: absolute; inset: 0 auto 0 0; width: 0; background: var(--seg); }\n.segment .recognition {\n  position: absolute; inset: 0 auto 0 0;\n  background: repeating-linear-gradient(135deg, color-mix(in srgb, Canvas 50%, transparent) 0 2px, transparent 2px 5px);\n}\n.progress.has-segments .thumb { background: currentColor; box-shadow: 0 0 0 3px color-mix(in srgb, currentColor 20%, transparent); }\n.tooltip {\n  position: absolute; bottom: calc(100% + 4px); left: 0;\n  transform: translateX(-50%);\n  width: max-content; max-width: min(320px, 100%);\n  padding: 6px 9px;\n  border-radius: 8px;\n  /* colour stays the page's text colour here, so the background can be derived from it\u2026 */\n  background: var(--cc-tooltip-bg);\n  font: 500 12px/1.35 system-ui, sans-serif;\n  pointer-events: none;\n  z-index: 2;\n  box-shadow: 0 6px 18px -8px rgb(0 0 0 / 0.5);\n}\n/* \u2026and the text inverts it. */\n.tooltip .tip { color: var(--cc-tooltip-fg); }\n.tooltip[hidden] { display: none; }\n.labels { display: none; position: relative; height: 18px; margin-top: -4px; }\n:host([segment-labels]) .labels { display: block; }\n.label {\n  position: absolute; top: 0;\n  min-width: 0; height: 18px; padding: 0 2px;\n  background: none; border-radius: 4px;\n  color: inherit; opacity: 0.6;\n  font: 500 11px/18px system-ui, sans-serif;\n  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;\n}\n.label:hover { background: var(--cc-control-bg); opacity: 1; transform: none; }\n.label:active { transform: none; }\n.label.current { opacity: 1; font-weight: 700; }\n.marker {\n  position: absolute; top: 50%;\n  width: 2px; height: calc(var(--cc-progress-height) + 8px);\n  border-radius: 1px;\n  background: var(--cc-marker);\n  transform: translate(-50%, -50%);\n  pointer-events: none;\n}\n:host(:not([markers])) .marker { display: none; }\n.progress:focus-visible .track { outline: 2px solid var(--cc-accent); outline-offset: 4px; }\n\n/* \u2500\u2500\u2500 controls \u2500\u2500\u2500 */\n/* time | buttons | speed \u2014 the buttons stay centred whatever the time text's width */\n.controls { display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: var(--cc-controls-gap); }\n.buttons { display: flex; gap: var(--cc-controls-gap); }\n.time { justify-self: start; }\n.speed { justify-self: end; }\n/* Narrow players: buttons on top, time and speed below. */\n@container (max-width: 300px) {\n  .controls { grid-template-columns: 1fr 1fr; grid-template-areas: \"buttons buttons\" \"time speed\"; }\n  .buttons { grid-area: buttons; justify-content: center; }\n  .time { grid-area: time; }\n  .speed { grid-area: speed; }\n}\n:host([controls=\"none\"]) .controls { display: none; }\n/* Live (following a smart cube): nothing to replay. */\n:host([live]) .controls, :host([live]) .progress { display: none; }\nbutton {\n  display: inline-grid; place-items: center;\n  min-width: var(--cc-button-size); height: var(--cc-button-size);\n  padding: 0 8px;\n  border: 0;\n  border-radius: var(--cc-control-radius);\n  background: var(--cc-control-bg);\n  color: var(--cc-control-fg);\n  font: 600 12px/1 var(--cc-font);\n  cursor: pointer;\n  transition: background 0.12s ease, transform 0.08s ease;\n}\nbutton:hover { background: var(--cc-control-bg-hover); }\nbutton:active { transform: scale(0.94); }\nbutton:focus-visible { outline: 2px solid var(--cc-accent); outline-offset: 2px; }\nbutton:disabled { opacity: 0.4; cursor: default; transform: none; }\n/* Icons never take the click: it always lands on the button itself, even if the icon changes mid-click. */\nbutton svg { width: 18px; height: 18px; display: block; fill: currentColor; pointer-events: none; }\n.play { min-width: calc(var(--cc-button-size) * 1.25); background: var(--cc-accent); color: #fff; }\n.play:hover { background: color-mix(in srgb, var(--cc-accent) 85%, #000); }\n.time { font: 500 12px/1 var(--cc-font); opacity: 0.75; white-space: nowrap; font-variant-numeric: tabular-nums; }\n";
+/** Inline icons (no icon font, no network). */
+export declare const ICONS: {
+    readonly start: "<svg viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"M6 5h2v14H6zM20 5.5v13a.5.5 0 0 1-.78.42L9.5 12.4a.5.5 0 0 1 0-.8l9.72-6.52A.5.5 0 0 1 20 5.5z\"/></svg>";
+    readonly back: "<svg viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"M17 6.2v11.6a.5.5 0 0 1-.8.4L8 12.4a.5.5 0 0 1 0-.8l8.2-5.8a.5.5 0 0 1 .8.4zM6 6h2v12H6z\"/></svg>";
+    readonly play: "<svg viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"M8 5.6v12.8a.6.6 0 0 0 .92.5l10.1-6.4a.6.6 0 0 0 0-1L8.92 5.1a.6.6 0 0 0-.92.5z\"/></svg>";
+    readonly pause: "<svg viewBox=\"0 0 24 24\" aria-hidden=\"true\"><rect x=\"6.5\" y=\"5\" width=\"4\" height=\"14\" rx=\"1\"/><rect x=\"13.5\" y=\"5\" width=\"4\" height=\"14\" rx=\"1\"/></svg>";
+    readonly forward: "<svg viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"M7 6.2v11.6a.5.5 0 0 0 .8.4l8.2-5.8a.5.5 0 0 0 0-.8L7.8 5.8a.5.5 0 0 0-.8.4zM16 6h2v12h-2z\"/></svg>";
+    readonly end: "<svg viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"M16 5h2v14h-2zM4 5.5v13a.5.5 0 0 0 .78.42l9.72-6.52a.5.5 0 0 0 0-.8L4.78 5.08A.5.5 0 0 0 4 5.5z\"/></svg>";
+};

package/element/styles.js

@@ -0,0 +1,196 @@
+/**
+ * Default look of <cube-player>. Everything is themable from outside:
+ *
+ * - CSS custom properties on the element (or any ancestor) — quick theming:
+ *     --cc-accent            play button, progress fill, focus ring
+ *     --cc-control-bg        button background        --cc-control-bg-hover
+ *     --cc-control-fg        button icon colour       --cc-control-radius
+ *     --cc-button-size       button height/width      --cc-controls-gap
+ *     --cc-progress-height   bar thickness            --cc-progress-track / --cc-progress-fill
+ *     --cc-marker            stage marker colour      --cc-thumb-size
+ *     --cc-font              time / speed text
+ * - ::part() for anything else: stage, flat (the 2D picture), progress, progress-track,
+ *   progress-fill, progress-thumb, progress-marker, segment (+ segment-<id>),
+ *   segment-played, segment-recognition, segment-labels, segment-label
+ *   (+ segment-label-<id>), tooltip, tooltip-text, controls, buttons, button,
+ *   button-start, button-back, button-play, button-forward, button-end,
+ *   button-speed, time.
+ * - Replace the controls entirely: put your own element in slot="controls"
+ *   (or set controls="none") and drive the player's API.
+ *
+ * Colours derive from `currentColor`, so the defaults fit light and dark pages.
+ */
+export const STYLES = /* css */ `
+:host {
+  --cc-accent: #4f8cff;
+  --cc-control-bg: color-mix(in srgb, currentColor 8%, transparent);
+  --cc-control-bg-hover: color-mix(in srgb, currentColor 15%, transparent);
+  --cc-control-fg: currentColor;
+  --cc-control-radius: 10px;
+  --cc-button-size: 34px;
+  --cc-controls-gap: 5px;
+  --cc-progress-height: 6px;
+  --cc-progress-track: color-mix(in srgb, currentColor 14%, transparent);
+  --cc-progress-fill: var(--cc-accent);
+  --cc-marker: color-mix(in srgb, currentColor 55%, transparent);
+  --cc-thumb-size: 14px;
+  --cc-font: ui-monospace, "SF Mono", Menlo, monospace;
+  /* sections of the progress bar */
+  --cc-segment-1: #4f8cff;
+  --cc-segment-2: #22c55e;
+  --cc-segment-3: #f59e0b;
+  --cc-segment-4: #ef4444;
+  --cc-segment-5: #a855f7;
+  --cc-segment-6: #14b8a6;
+  --cc-segment-7: #ec4899;
+  --cc-segment-8: #eab308;
+  --cc-segment-height: calc(var(--cc-progress-height) + 2px);
+  --cc-segment-gap: 2px;
+  --cc-segment-unplayed: 30%;
+  /* popup: inverted page colours by default (text colour as background) */
+  --cc-tooltip-bg: color-mix(in srgb, currentColor 92%, transparent);
+  --cc-tooltip-fg: Canvas;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  min-width: 200px;
+  min-height: 200px;
+  outline: none;
+  container-type: inline-size;
+}
+:host([hidden]) { display: none; }
+.stage { position: relative; flex: 1; min-height: 0; }
+.flat { position: absolute; inset: 0; display: grid; place-items: center; }
+.flat[hidden] { display: none; }
+.flat svg { width: 100%; height: 100%; }
+
+/* ─── progress bar ─── */
+.progress { display: none; padding: 6px 2px; cursor: pointer; touch-action: none; }
+:host([progress]) .progress { display: block; }
+.track {
+  position: relative;
+  height: var(--cc-progress-height);
+  border-radius: 999px;
+  background: var(--cc-progress-track);
+}
+.fill {
+  position: absolute; inset: 0 auto 0 0;
+  width: 0;
+  border-radius: inherit;
+  background: var(--cc-progress-fill);
+}
+.thumb {
+  position: absolute; top: 50%; left: 0;
+  width: var(--cc-thumb-size); height: var(--cc-thumb-size);
+  border-radius: 50%;
+  background: var(--cc-progress-fill);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--cc-progress-fill) 25%, transparent);
+  transform: translate(-50%, -50%) scale(0.85);
+  transition: transform 0.12s ease;
+}
+.progress:hover .thumb, .progress.dragging .thumb { transform: translate(-50%, -50%) scale(1); }
+/* Sections: coloured parts of the bar, dim until played, recognition hatched. */
+.progress { position: relative; }
+.progress.has-segments .fill { display: none; }
+.segments { position: absolute; inset: 0; }
+.segment {
+  position: absolute; top: 50%;
+  height: var(--cc-segment-height);
+  transform: translateY(-50%);
+  overflow: hidden;
+  background: color-mix(in srgb, var(--seg) var(--cc-segment-unplayed), transparent);
+  clip-path: inset(0 calc(var(--cc-segment-gap) / 2) 0 calc(var(--cc-segment-gap) / 2) round 999px);
+}
+.segment .played { position: absolute; inset: 0 auto 0 0; width: 0; background: var(--seg); }
+.segment .recognition {
+  position: absolute; inset: 0 auto 0 0;
+  background: repeating-linear-gradient(135deg, color-mix(in srgb, Canvas 50%, transparent) 0 2px, transparent 2px 5px);
+}
+.progress.has-segments .thumb { background: currentColor; box-shadow: 0 0 0 3px color-mix(in srgb, currentColor 20%, transparent); }
+.tooltip {
+  position: absolute; bottom: calc(100% + 4px); left: 0;
+  transform: translateX(-50%);
+  width: max-content; max-width: min(320px, 100%);
+  padding: 6px 9px;
+  border-radius: 8px;
+  /* colour stays the page's text colour here, so the background can be derived from it… */
+  background: var(--cc-tooltip-bg);
+  font: 500 12px/1.35 system-ui, sans-serif;
+  pointer-events: none;
+  z-index: 2;
+  box-shadow: 0 6px 18px -8px rgb(0 0 0 / 0.5);
+}
+/* …and the text inverts it. */
+.tooltip .tip { color: var(--cc-tooltip-fg); }
+.tooltip[hidden] { display: none; }
+.labels { display: none; position: relative; height: 18px; margin-top: -4px; }
+:host([segment-labels]) .labels { display: block; }
+.label {
+  position: absolute; top: 0;
+  min-width: 0; height: 18px; padding: 0 2px;
+  background: none; border-radius: 4px;
+  color: inherit; opacity: 0.6;
+  font: 500 11px/18px system-ui, sans-serif;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.label:hover { background: var(--cc-control-bg); opacity: 1; transform: none; }
+.label:active { transform: none; }
+.label.current { opacity: 1; font-weight: 700; }
+.marker {
+  position: absolute; top: 50%;
+  width: 2px; height: calc(var(--cc-progress-height) + 8px);
+  border-radius: 1px;
+  background: var(--cc-marker);
+  transform: translate(-50%, -50%);
+  pointer-events: none;
+}
+:host(:not([markers])) .marker { display: none; }
+.progress:focus-visible .track { outline: 2px solid var(--cc-accent); outline-offset: 4px; }
+
+/* ─── controls ─── */
+/* time | buttons | speed — the buttons stay centred whatever the time text's width */
+.controls { display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: var(--cc-controls-gap); }
+.buttons { display: flex; gap: var(--cc-controls-gap); }
+.time { justify-self: start; }
+.speed { justify-self: end; }
+/* Narrow players: buttons on top, time and speed below. */
+@container (max-width: 300px) {
+  .controls { grid-template-columns: 1fr 1fr; grid-template-areas: "buttons buttons" "time speed"; }
+  .buttons { grid-area: buttons; justify-content: center; }
+  .time { grid-area: time; }
+  .speed { grid-area: speed; }
+}
+:host([controls="none"]) .controls { display: none; }
+/* Live (following a smart cube): nothing to replay. */
+:host([live]) .controls, :host([live]) .progress { display: none; }
+button {
+  display: inline-grid; place-items: center;
+  min-width: var(--cc-button-size); height: var(--cc-button-size);
+  padding: 0 8px;
+  border: 0;
+  border-radius: var(--cc-control-radius);
+  background: var(--cc-control-bg);
+  color: var(--cc-control-fg);
+  font: 600 12px/1 var(--cc-font);
+  cursor: pointer;
+  transition: background 0.12s ease, transform 0.08s ease;
+}
+button:hover { background: var(--cc-control-bg-hover); }
+button:active { transform: scale(0.94); }
+button:focus-visible { outline: 2px solid var(--cc-accent); outline-offset: 2px; }
+button:disabled { opacity: 0.4; cursor: default; transform: none; }
+/* Icons never take the click: it always lands on the button itself, even if the icon changes mid-click. */
+button svg { width: 18px; height: 18px; display: block; fill: currentColor; pointer-events: none; }
+.play { min-width: calc(var(--cc-button-size) * 1.25); background: var(--cc-accent); color: #fff; }
+.play:hover { background: color-mix(in srgb, var(--cc-accent) 85%, #000); }
+.time { font: 500 12px/1 var(--cc-font); opacity: 0.75; white-space: nowrap; font-variant-numeric: tabular-nums; }
+`;
+/** Inline icons (no icon font, no network). */
+export const ICONS = {
+    start: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M6 5h2v14H6zM20 5.5v13a.5.5 0 0 1-.78.42L9.5 12.4a.5.5 0 0 1 0-.8l9.72-6.52A.5.5 0 0 1 20 5.5z"/></svg>',
+    back: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M17 6.2v11.6a.5.5 0 0 1-.8.4L8 12.4a.5.5 0 0 1 0-.8l8.2-5.8a.5.5 0 0 1 .8.4zM6 6h2v12H6z"/></svg>',
+    play: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M8 5.6v12.8a.6.6 0 0 0 .92.5l10.1-6.4a.6.6 0 0 0 0-1L8.92 5.1a.6.6 0 0 0-.92.5z"/></svg>',
+    pause: '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="6.5" y="5" width="4" height="14" rx="1"/><rect x="13.5" y="5" width="4" height="14" rx="1"/></svg>',
+    forward: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M7 6.2v11.6a.5.5 0 0 0 .8.4l8.2-5.8a.5.5 0 0 0 0-.8L7.8 5.8a.5.5 0 0 0-.8.4zM16 6h2v12h-2z"/></svg>',
+    end: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M16 5h2v14h-2zM4 5.5v13a.5.5 0 0 0 .78.42l9.72-6.52a.5.5 0 0 0 0-.8L4.78 5.08A.5.5 0 0 0 4 5.5z"/></svg>',
+};

package/image/cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Caching SVG output. `svgKey` is a stable string for (state, options) — use it
+ * as a key for an in-memory LRU, IndexedDB, localStorage, a CDN path or a
+ * server-side file name. Rendering is deterministic, so equal keys mean equal
+ * images.
+ */
+import type { State } from "../core/index.js";
+import { type SvgOptions } from "./svg.js";
+export declare function svgKey(state: State, options?: SvgOptions): string;
+/** Small LRU of rendered SVG strings. */
+export declare class SvgCache {
+    private readonly max;
+    private map;
+    constructor(max?: number);
+    get(state: State, options?: SvgOptions): string;
+    get size(): number;
+}
+/** `data:` URL for an <img src>. */
+export declare const svgDataUrl: (svg: string) => string;
+/** Browser only: rasterise to a PNG Blob (uses an offscreen canvas). */
+export declare function svgToPngBlob(svg: string, width: number): Promise<Blob>;

package/image/cache.js

@@ -0,0 +1,66 @@
+/**
+ * Caching SVG output. `svgKey` is a stable string for (state, options) — use it
+ * as a key for an in-memory LRU, IndexedDB, localStorage, a CDN path or a
+ * server-side file name. Rendering is deterministic, so equal keys mean equal
+ * images.
+ */
+import { renderSvg } from "./svg.js";
+const hex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+/** Short FNV-1a hash — keys stay short enough for file names and URLs. */
+function fnv(text) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h.toString(36);
+}
+export function svgKey(state, options = {}) {
+    const { mask, frame, skin, spins, ...rest } = options;
+    const parts = [
+        hex(state),
+        mask ? hex(mask) : "",
+        frame ? String(frame.id) : "0",
+        skin ? JSON.stringify(skin) : "",
+        spins && skin?.decals?.length ? hex(spins) : "",
+        JSON.stringify(rest, Object.keys(rest).sort()),
+    ];
+    return `${options.view ?? "iso"}-${fnv(parts.join("|"))}-${fnv(parts.reverse().join("|"))}`;
+}
+/** Small LRU of rendered SVG strings. */
+export class SvgCache {
+    max;
+    map = new Map();
+    constructor(max = 500) {
+        this.max = max;
+    }
+    get(state, options = {}) {
+        const key = svgKey(state, options);
+        const hit = this.map.get(key);
+        if (hit !== undefined) {
+            this.map.delete(key);
+            this.map.set(key, hit);
+            return hit;
+        }
+        const svg = renderSvg(state, options);
+        this.map.set(key, svg);
+        if (this.map.size > this.max)
+            this.map.delete(this.map.keys().next().value);
+        return svg;
+    }
+    get size() {
+        return this.map.size;
+    }
+}
+/** `data:` URL for an <img src>. */
+export const svgDataUrl = (svg) => `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+/** Browser only: rasterise to a PNG Blob (uses an offscreen canvas). */
+export async function svgToPngBlob(svg, width) {
+    const img = new Image();
+    img.src = svgDataUrl(svg);
+    await img.decode();
+    const height = Math.round((width * img.naturalHeight) / img.naturalWidth);
+    const canvas = new OffscreenCanvas(width, height);
+    canvas.getContext("2d").drawImage(img, 0, 0, width, height);
+    return canvas.convertToBlob({ type: "image/png" });
+}

package/image/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./svg.js";
+export * from "./cache.js";

package/image/index.js

@@ -0,0 +1,2 @@
+export * from "./svg.js";
+export * from "./cache.js";

package/image/png-node.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Server-side PNG (Node / Bun), via @resvg/resvg-js — an optional dependency:
+ * install it only where you render PNGs on a server. Browsers use
+ * `svgToPngBlob` instead.
+ */
+export declare function svgToPng(svg: string, width?: number): Promise<Uint8Array>;

package/image/png-node.js

@@ -0,0 +1,10 @@
+/**
+ * Server-side PNG (Node / Bun), via @resvg/resvg-js — an optional dependency:
+ * install it only where you render PNGs on a server. Browsers use
+ * `svgToPngBlob` instead.
+ */
+export async function svgToPng(svg, width) {
+    const { Resvg } = await import("@resvg/resvg-js");
+    const resvg = new Resvg(svg, width ? { fitTo: { mode: "width", value: width } } : undefined);
+    return resvg.render().asPng();
+}

package/image/svg.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Cube pictures as SVG strings — no DOM, no canvas: the same call works in a
+ * browser, a worker, or on a server (Node/Bun), and the output is a plain
+ * string you can cache, inline, serve or turn into PNG.
+ *
+ * Looks come from the same `Skin` as the 3D renderer (@cubecore/skin):
+ * colours, mask colours, tile shapes per piece kind, custom SVG tile outlines,
+ * stickerless tiles and the logo — one skin, one look in 3D and in pictures.
+ *
+ * Views:
+ *   "iso" — 3D-looking cube showing U, F and R (like a case card)
+ *   "top" — last-layer diagram: U face plus the side stickers of the top layer
+ *   "net" — unfolded cube (U on top, L F R B across, D below)
+ *
+ * Every tile is drawn in its face's own (a, b) coordinates and then mapped to
+ * the picture by an affine projection per view, so shapes, paths and logos
+ * work the same way in all three views.
+ */
+import { type CenterSpins, type Frame, type Mask, type State } from "../core/index.js";
+import { type Skin, type Theme } from "../skin/index.js";
+export type View = "iso" | "top" | "net";
+export interface SvgOptions {
+    view?: View;
+    /** Output width in px (height follows the view's aspect ratio). */
+    size?: number;
+    /** Looks — the same skin the 3D renderer uses. Default `SKINS.default`. */
+    skin?: Skin;
+    mask?: Mask;
+    /** Draw the cube as held in this frame (e.g. to show a case with the cross on D whatever face it was solved on). */
+    frame?: Frame;
+    /** Centre spins (see `spinsAfter`) — only matter for decals on centres. Default: all upright. */
+    spins?: CenterSpins;
+    /** Page theme the skin is adjusted for (skin.themes). Default "dark". */
+    theme?: Theme;
+}
+export declare function renderSvg(state: State, options?: SvgOptions): string;