pomium 1.0.0

package/src/pom/index.js

@@ -0,0 +1,173 @@
+import { IDLE_TEARDOWN_MS, ATLAS_CACHE_LIMIT } from './config.js';
+import { attachOverlay } from './overlay.js';
+import { createEngine, createRoster } from './engine.js';
+import { createAtlasCache } from './atlas.js';
+import { createAtlasLoader } from './atlas-loader.js';
+import { createLoop } from './loop.js';
+import { renderScene } from './render.js';
+
+// Pre-decode defaults used only to size a sprite before its atlas has
+// loaded; the decoded atlas is the real source of truth once it lands.
+const FRAME_COUNTS = { shockwave: 17 };
+const DEFAULT_CHARACTER_FRAMES = 96;
+
+// A desktop browser window is never below the mobile breakpoint.
+const TIER = 'desktop';
+
+export function createPoms({ canvas, assetsDir, onShake }) {
+  if (window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+    return { pointerDown() {}, pointerMove() {}, pointerUp() {}, resize() {}, destroy() {} };
+  }
+
+  let overlay = null;
+  let engine = null;
+  let loop = null;
+  let cache = null;
+  let roster = null;
+  let idleTimer = null;
+  let resizeHandle = null;
+  // Last offset handed to onShake. The shake decays in SHAKE_DURATION updates
+  // but sprites live far longer, so an unconditional send would repeat the
+  // same settled payload across the process boundary for the rest of their
+  // life and the whole idle window after it.
+  let lastShake = null;
+
+  function emitShake(x, y, settled) {
+    if (!onShake) return;
+    if (lastShake && lastShake.x === x && lastShake.y === y && lastShake.settled === settled) return;
+    lastShake = { x, y, settled };
+    onShake(x, y, settled);
+  }
+
+  function frameCountFor(key) {
+    return FRAME_COUNTS[key] ?? DEFAULT_CHARACTER_FRAMES;
+  }
+
+  function warm(key) {
+    cache.get(key).catch(() => {});
+  }
+
+  // A transient decode failure would otherwise kill that character for the
+  // session, since the renderer only ever peeks the cache. Re-warm whatever
+  // the roster is missing on each press, so a failure heals on the next click.
+  function rewarmMissing() {
+    if (!cache || !roster) return;
+    if (!cache.peek('shockwave')) warm('shockwave');
+    for (const key of roster) {
+      if (!cache.peek(key)) warm(key);
+    }
+  }
+
+  function teardown() {
+    if (loop) loop.stop();
+    if (overlay) overlay.destroy();
+    if (cache) cache.clear();
+    if (idleTimer !== null) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+    if (resizeHandle !== null) {
+      cancelAnimationFrame(resizeHandle);
+      resizeHandle = null;
+    }
+    overlay = null; engine = null; loop = null; cache = null;
+    roster = null;
+    lastShake = null;
+    emitShake(0, 0, true);
+  }
+
+  function scheduleIdleCheck() {
+    if (idleTimer !== null) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      if (engine && engine.isIdle) teardown();
+      else if (engine) scheduleIdleCheck();
+    }, IDLE_TEARDOWN_MS);
+  }
+
+  function ensureStarted() {
+    if (engine) {
+      if (!loop.running) loop.start();
+      scheduleIdleCheck();
+      return;
+    }
+
+    try {
+      overlay = attachOverlay(canvas);
+      cache = createAtlasCache({
+        limit: ATLAS_CACHE_LIMIT,
+        load: createAtlasLoader({ tier: TIER, assetsDir }),
+      });
+
+      // One roster per session, so at most ROSTER_SIZE + 1 atlases are live.
+      roster = createRoster();
+      warm('shockwave');
+      for (const key of roster) warm(key);
+
+      engine = createEngine({
+        width: overlay.width,
+        height: overlay.height,
+        roster,
+        frameCountFor,
+      });
+
+      loop = createLoop({
+        update: () => {
+          engine.update();
+          // The window takes x/y; the canvas takes rotation. Sending both to
+          // both would double the shake.
+          // isIdle means "no sprites left" — 96 frames — but the shake decays in 8
+          // updates. Treating a zero offset as settled releases the window as soon as
+          // the jolt actually ends, instead of pinning it for the sprite's whole life.
+          const settled = engine.isIdle || (engine.camera.x === 0 && engine.camera.y === 0);
+          emitShake(engine.camera.x, engine.camera.y, settled);
+          if (engine.isIdle) loop.stop();
+        },
+        render: () => renderScene(overlay.ctx, {
+          sprites: engine.sprites,
+          camera: { x: 0, y: 0, rotation: engine.camera.rotation },
+          atlases: { get: (key) => cache.peek(key) },
+          width: overlay.width,
+          height: overlay.height,
+        }),
+      });
+      loop.start();
+      scheduleIdleCheck();
+    } catch (error) {
+      // Never break the browser chrome. If any of this throws, leaving engine
+      // non-null would throw again on every later click, forever.
+      console.warn('[pomium] failed to start', error);
+      if (overlay) overlay.destroy();
+      if (cache) cache.clear();
+      overlay = null; engine = null; loop = null; cache = null; roster = null;
+      lastShake = null;
+    }
+  }
+
+  return {
+    pointerDown(x) {
+      ensureStarted();
+      if (!engine) return;
+      rewarmMissing();
+      engine.pointerDown(x);
+    },
+    pointerMove(x) {
+      if (engine) engine.pointerMove(x);
+    },
+    pointerUp() {
+      if (engine) engine.pointerUp();
+    },
+    resize() {
+      if (!overlay || !engine) return;
+      // The window fires resize continuously during a drag, and each resize
+      // reallocates a full-viewport backing store. Coalesce to one per frame.
+      if (resizeHandle !== null) return;
+      resizeHandle = requestAnimationFrame(() => {
+        resizeHandle = null;
+        if (!overlay || !engine) return;
+        overlay.resize();
+        engine.resize(overlay.width, overlay.height);
+      });
+    },
+    destroy: teardown,
+  };
+}

package/src/pom/loop.js

@@ -0,0 +1,68 @@
+import { UPDATES_PER_SECOND } from './config.js';
+
+const MAX_CATCH_UP = 5;
+
+// Fixed-timestep loop: update() always advances the simulation by `step` ms
+// regardless of the display's refresh rate. The reference implementation
+// this replaces steps its simulation on every second tick of a 60Hz ticker,
+// so it silently runs at double speed on a 120Hz display. Accumulating real
+// elapsed time and draining it in fixed `step` increments keeps the
+// simulation rate constant across refresh rates, while render() still runs
+// once per scheduled frame so drawing stays at the display's native rate.
+export function createLoop({
+  update,
+  render,
+  step = 1000 / UPDATES_PER_SECOND,
+  now = () => performance.now(),
+  schedule = (fn) => requestAnimationFrame(fn),
+  cancel = (handle) => cancelAnimationFrame(handle),
+}) {
+  let handle = null;
+  let running = false;
+  let last = 0;
+  let accumulator = 0;
+
+  function frame() {
+    handle = null;
+    const time = now();
+    accumulator += time - last;
+    last = time;
+
+    let steps = 0;
+    while (accumulator >= step && steps < MAX_CATCH_UP) {
+      accumulator -= step;
+      steps += 1;
+      update();
+    }
+    if (steps === MAX_CATCH_UP) accumulator = 0;
+
+    render();
+
+    // update() or render() may have called stop() re-entrantly (e.g. the
+    // engine going idle mid-update). running is the source of truth for
+    // whether this frame should reschedule itself; handle alone can't tell
+    // the difference between "never started" and "stopped mid-callback",
+    // since it was already nulled above.
+    if (running) {
+      handle = schedule(frame);
+    }
+  }
+
+  return {
+    start() {
+      if (running) return;
+      running = true;
+      last = now();
+      accumulator = 0;
+      handle = schedule(frame);
+    },
+    stop() {
+      running = false;
+      if (handle !== null) cancel(handle);
+      handle = null;
+    },
+    get running() {
+      return running;
+    },
+  };
+}

package/src/pom/overlay.js

@@ -0,0 +1,42 @@
+export function canvasBackingSize(cssWidth, cssHeight, dpr) {
+  const ratio = Math.min(3, Math.max(1, dpr || 1));
+  return {
+    width: Math.floor(cssWidth * ratio),
+    height: Math.floor(cssHeight * ratio),
+    dpr: ratio,
+  };
+}
+
+// The canvas already exists in the chrome's own HTML, so unlike the browser
+// extension this does not build a host element or a shadow root: there is no
+// hostile page CSS to defend against here. It only measures and sizes.
+export function attachOverlay(canvas) {
+  const ctx = canvas.getContext('2d', { alpha: true });
+  let destroyed = false;
+
+  const overlay = {
+    canvas,
+    ctx,
+    width: 0,
+    height: 0,
+    resize() {
+      if (destroyed) return;
+      const rect = canvas.getBoundingClientRect();
+      const cssWidth = rect.width || window.innerWidth;
+      const cssHeight = rect.height || window.innerHeight;
+      const size = canvasBackingSize(cssWidth, cssHeight, window.devicePixelRatio);
+      canvas.width = size.width;
+      canvas.height = size.height;
+      ctx.setTransform(size.dpr, 0, 0, size.dpr, 0, 0);
+      overlay.width = cssWidth;
+      overlay.height = cssHeight;
+    },
+    destroy() {
+      destroyed = true;
+      ctx.clearRect(0, 0, overlay.width, overlay.height);
+    },
+  };
+
+  overlay.resize();
+  return overlay;
+}

package/src/pom/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/src/pom/render.js

@@ -0,0 +1,32 @@
+import { POM_ANCHOR, SHOCKWAVE_ANCHOR } from './config.js';
+
+export function spriteDrawArgs(sprite, frame) {
+  const anchor = sprite.isShockwave ? SHOCKWAVE_ANCHOR : POM_ANCHOR;
+  const scale = sprite.scale;
+  return {
+    sx: frame.sx, sy: frame.sy, sw: frame.sw, sh: frame.sh,
+    dx: Math.round(sprite.x - anchor.x * frame.sourceW * scale + frame.ox * scale),
+    dy: Math.round(sprite.y - anchor.y * frame.sourceH * scale + frame.oy * scale),
+    dw: frame.sw * scale,
+    dh: frame.sh * scale,
+  };
+}
+
+export function renderScene(ctx, { sprites, camera, atlases, width, height }) {
+  ctx.clearRect(0, 0, width, height);
+  ctx.save();
+  ctx.translate(width / 2 + camera.x, height / 2 + camera.y);
+  ctx.rotate(camera.rotation);
+  ctx.translate(-width / 2, -height / 2);
+
+  for (const sprite of sprites) {
+    const atlas = atlases.get(sprite.key);
+    if (!atlas) continue;
+    const frame = atlas.frames[sprite.frame];
+    if (!frame) continue;
+    const a = spriteDrawArgs(sprite, frame);
+    ctx.drawImage(atlas.image, a.sx, a.sy, a.sw, a.sh, a.dx, a.dy, a.dw, a.dh);
+  }
+
+  ctx.restore();
+}

package/src/pom/sprites.js

@@ -0,0 +1,66 @@
+import { CULL_MARGIN, MAX_ACTIVE } from './config.js';
+import { depthFactor, scaleForDepth, speedMultForDepth } from './geometry.js';
+
+export function createSprite({ key, isShockwave, x, y, vx, vy, frameCount }) {
+  return {
+    key, isShockwave, x, y, vx, vy, frameCount,
+    frame: 0, scale: 0.5, zIndex: 0, retired: false,
+  };
+}
+
+export function integrate(sprite, height) {
+  const depth = depthFactor(sprite.y, height);
+  const scale = scaleForDepth(depth);
+  const speedMult = speedMultForDepth(depth);
+  sprite.scale = scale;
+  sprite.zIndex = sprite.isShockwave ? scale - 10 : scale;
+  sprite.x += sprite.vx * speedMult * 2;
+  sprite.y += sprite.vy * speedMult * 2;
+}
+
+export function advanceFrame(sprite) {
+  if (sprite.frame < sprite.frameCount - 1) {
+    sprite.frame += 1;
+  } else {
+    sprite.retired = true;
+  }
+}
+
+export function isCulled(sprite, width, height) {
+  return (
+    sprite.x > width + CULL_MARGIN || sprite.x < -CULL_MARGIN ||
+    sprite.y > height + CULL_MARGIN || sprite.y < -CULL_MARGIN
+  );
+}
+
+export class SpriteList {
+  constructor(limit = MAX_ACTIVE) {
+    this.limit = limit;
+    this.items = [];
+    this.nextSeq = 0;
+  }
+
+  add(sprite) {
+    // Insertion order is tracked explicitly via a monotonic sequence number,
+    // not inferred from array position: engine.update() sorts this.items by
+    // zIndex in place every tick (draw order), so by the time add() runs
+    // again the array is no longer in insertion order. Evicting by splice(0,
+    // n) against that sorted array evicted whatever a shockwave's zIndex
+    // (scale - 10) put first, not the oldest sprite.
+    sprite.seq = this.nextSeq;
+    this.nextSeq += 1;
+    this.items.push(sprite);
+    if (this.items.length > this.limit) {
+      const excess = this.items.length - this.limit;
+      const oldest = [...this.items].sort((a, b) => a.seq - b.seq).slice(0, excess);
+      const evict = new Set(oldest);
+      this.items = this.items.filter((s) => !evict.has(s));
+    }
+  }
+
+  prune(width, height) {
+    this.items = this.items.filter(
+      (s) => !s.retired && !isCulled(s, width, height)
+    );
+  }
+}

package/src/renderer/index.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8" />
+  <title>Pomium</title>
+  <link rel="stylesheet" href="./styles.css" />
+</head>
+<body>
+  <div id="tab-strip">
+    <div id="tabs"></div>
+    <button id="new-tab-btn" title="New tab">+</button>
+  </div>
+  <div id="toolbar">
+    <button id="back-btn" title="Back">&#8592;</button>
+    <button id="fwd-btn" title="Forward">&#8594;</button>
+    <button id="reload-btn" title="Reload">&#8635;</button>
+    <input id="address-bar" type="text" placeholder="Search or enter address" />
+    <button id="go-btn" title="Go">Go</button>
+  </div>
+  <div id="content"></div>
+  <canvas id="pom-overlay"></canvas>
+
+  <script src="./renderer.js"></script>
+</body>
+</html>

package/src/renderer/renderer.js

@@ -0,0 +1,197 @@
+const path = require('path');
+const { ipcRenderer } = require('electron');
+
+// src/pom/ is ESM (scoped by its own package.json) while this file is
+// CommonJS, so it is pulled in with a dynamic import.
+let poms = null;
+let windowX = null;
+
+// Which document started the drag in progress: 'chrome', 'webview', or null
+// when nothing is held. Focus crossing between the host chrome and a
+// <webview> fires blur on whichever side is losing it, and a blur handler
+// that released unconditionally would kill a drag the user is still
+// physically holding. Whoever owns the drag owns its release.
+let dragSource = null;
+
+(async () => {
+  const pomUrl = 'file://' + path.join(__dirname, '..', 'pom', 'index.js');
+  const coordsUrl = 'file://' + path.join(__dirname, '..', 'pom', 'coords.js');
+  const [{ createPoms }, coords] = await Promise.all([import(pomUrl), import(coordsUrl)]);
+  windowX = coords.windowX;
+
+  poms = createPoms({
+    canvas: document.getElementById('pom-overlay'),
+    assetsDir: path.join(__dirname, '..', '..', 'assets'),
+    onShake: (x, y, settled) => ipcRenderer.send('pom-shake', { x, y, settled }),
+  });
+
+  // Clicks on the chrome itself — tab strip, toolbar, address bar — spawn too.
+  // Page clicks cannot reach here; they arrive over IPC in createTab.
+  document.addEventListener('pointerdown', (e) => {
+    if (e.button !== undefined && e.button !== 0) return;
+    dragSource = 'chrome';
+    poms.pointerDown(e.clientX);
+  }, { capture: true, passive: true });
+  document.addEventListener('pointermove', (e) => {
+    // The engine only reads the pointer position while a chrome drag is
+    // held, so an unguarded handler would do a call per mouse move for
+    // nothing. Mirrors the held check in webview-preload.js.
+    if (dragSource !== 'chrome') return;
+    poms.pointerMove(e.clientX);
+  }, { capture: true, passive: true });
+  document.addEventListener('pointerup', (e) => {
+    if (e.button !== undefined && e.button !== 0) return;
+    dragSource = null;
+    poms.pointerUp();
+  }, { capture: true, passive: true });
+  document.addEventListener('pointercancel', () => {
+    dragSource = null;
+    poms.pointerUp();
+  }, { capture: true, passive: true });
+  window.addEventListener('blur', () => {
+    // Pressing into a <webview> blurs the host document even though the
+    // pointer never left the window. The page's own preload mirrors this
+    // handler for real window-level focus loss, so the webview releases
+    // its own drags and this one must not.
+    if (dragSource === 'webview') return;
+    dragSource = null;
+    poms.pointerUp();
+  }, { passive: true });
+
+  window.addEventListener('resize', () => poms.resize(), { passive: true });
+})();
+
+const WEBVIEW_PRELOAD_URL = 'file://' + path.join(__dirname, '..', 'webview-preload.js');
+const DEFAULT_URL = 'https://www.google.com';
+
+const tabsEl = document.getElementById('tabs');
+const contentEl = document.getElementById('content');
+const addressBar = document.getElementById('address-bar');
+
+let tabs = [];
+let activeId = null;
+
+function normalizeUrl(input) {
+  input = (input || '').trim();
+  if (!input) return DEFAULT_URL;
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(input)) return input;
+  if (/^[\w-]+(\.[\w-]+)+(\/.*)?$/i.test(input) && !input.includes(' ')) {
+    return 'https://' + input;
+  }
+  return 'https://www.google.com/search?q=' + encodeURIComponent(input);
+}
+
+function currentTab() {
+  return tabs.find((t) => t.id === activeId);
+}
+
+function createTab(url) {
+  const id = 'tab-' + Date.now() + '-' + Math.random().toString(36).slice(2, 7);
+
+  const webview = document.createElement('webview');
+  webview.className = 'browser-webview';
+  webview.setAttribute('preload', WEBVIEW_PRELOAD_URL);
+  webview.setAttribute('allowpopups', '');
+  webview.src = url || DEFAULT_URL;
+
+  const pane = document.createElement('div');
+  pane.className = 'webview-pane';
+  pane.appendChild(webview);
+  contentEl.appendChild(pane);
+
+  const titleSpan = document.createElement('span');
+  titleSpan.className = 'tab-title';
+  titleSpan.textContent = 'New Tab';
+
+  const closeBtn = document.createElement('span');
+  closeBtn.className = 'tab-close';
+  closeBtn.textContent = '×';
+  closeBtn.addEventListener('click', (e) => {
+    e.stopPropagation();
+    closeTab(id);
+  });
+
+  const tabBtn = document.createElement('div');
+  tabBtn.className = 'tab';
+  tabBtn.appendChild(titleSpan);
+  tabBtn.appendChild(closeBtn);
+  tabBtn.addEventListener('click', () => activateTab(id));
+  tabsEl.appendChild(tabBtn);
+
+  const tab = { id, webview, pane, tabBtn, titleSpan };
+  tabs.push(tab);
+
+  // pom-move only arrives while a drag is held (see webview-preload.js), so
+  // the pane's rect only needs reading once per drag rather than per message.
+  let dragRect = null;
+
+  webview.addEventListener('page-title-updated', (e) => {
+    titleSpan.textContent = e.title;
+  });
+  webview.addEventListener('did-navigate', (e) => {
+    if (tab.id === activeId) addressBar.value = e.url;
+  });
+  webview.addEventListener('did-navigate-in-page', (e) => {
+    if (tab.id === activeId) addressBar.value = e.url;
+  });
+  webview.addEventListener('ipc-message', (e) => {
+    if (!poms) return;
+    if (e.channel === 'pom-down') {
+      const { x = 0 } = e.args[0] || {};
+      dragRect = pane.getBoundingClientRect();
+      dragSource = 'webview';
+      poms.pointerDown(windowX(x, dragRect));
+    } else if (e.channel === 'pom-move') {
+      const { x = 0 } = e.args[0] || {};
+      poms.pointerMove(windowX(x, dragRect));
+    } else if (e.channel === 'pom-up') {
+      dragRect = null;
+      dragSource = null;
+      poms.pointerUp();
+    }
+  });
+
+  activateTab(id);
+  return tab;
+}
+
+function activateTab(id) {
+  activeId = id;
+  tabs.forEach((t) => {
+    const active = t.id === id;
+    t.pane.classList.toggle('active', active);
+    t.tabBtn.classList.toggle('active', active);
+    if (active) addressBar.value = t.webview.src;
+  });
+}
+
+function closeTab(id) {
+  const idx = tabs.findIndex((t) => t.id === id);
+  if (idx === -1) return;
+  const [tab] = tabs.splice(idx, 1);
+  tab.pane.remove();
+  tab.tabBtn.remove();
+  if (tabs.length === 0) {
+    createTab();
+    return;
+  }
+  if (activeId === id) {
+    activateTab(tabs[Math.max(0, idx - 1)].id);
+  }
+}
+
+function go() {
+  const tab = currentTab();
+  if (tab) tab.webview.loadURL(normalizeUrl(addressBar.value));
+}
+
+document.getElementById('new-tab-btn').addEventListener('click', () => createTab());
+document.getElementById('back-btn').addEventListener('click', () => currentTab()?.webview.goBack());
+document.getElementById('fwd-btn').addEventListener('click', () => currentTab()?.webview.goForward());
+document.getElementById('reload-btn').addEventListener('click', () => currentTab()?.webview.reload());
+document.getElementById('go-btn').addEventListener('click', go);
+addressBar.addEventListener('keydown', (e) => {
+  if (e.key === 'Enter') go();
+});
+
+createTab(DEFAULT_URL);