@weasel-js/loupe 1.4.0-pre.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @weasel-js/loupe
+
+The magnifier's model, with no surface attached: where it is aimed, how far it
+magnifies, whether it is showing re-rendered content or actual pixels, and what
+colour it is over.
+
+A **painter** draws it on one kind of surface and answers the few questions the
+model asks — does the lens cover this point, what colour is here, repaint. The
+painters ship with the surfaces they know: `@weasel-js/hud` draws one into a
+WebGL canvas, `@weasel-js/labkit` draws one over a lab's own content.
+
+```ts
+import { createLoupeModel } from '@weasel-js/loupe';
+
+const loupe = createLoupeModel({ surface, factor: 8 });
+loupe.aimAt({ x, y });
+```

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import { View } from '@weasel-js/core';
+
+/** A point on the magnified surface, in its own CSS pixels. */
+interface LoupePoint {
+    x: number;
+    y: number;
+}
+/** The lens' rectangle on that surface. */
+interface LoupeRect extends LoupePoint {
+    w: number;
+    h: number;
+}
+/**
+ * The inner `View` a loupe renders its content through: the outer view's
+ * magnification times `factor`, positioned so `target` sits at the center of
+ * a viewport the size of `rect`.
+ */
+declare function loupeInnerView(target: LoupePoint, outer: View, rect: LoupeRect, factor: number): View;
+/**
+ * Where on the outer surface a point inside the lens is looking, in
+ * screen-space CSS px.
+ *
+ * The inverse of {@link loupeInnerView}: the lens centers `aim` in `rect` and
+ * magnifies by `factor`, and the outer view's own scale cancels out of the
+ * round trip — so this needs no `View`.
+ */
+declare function loupeSourcePoint(p: LoupePoint, rect: LoupeRect, aim: LoupePoint, factor: number): LoupePoint;
+
+/** How a loupe magnifies. `'vector'` re-renders the source through a zoomed-in
+ *  view, so content stays sharp at any factor; `'pixel'` blows up the actual
+ *  pixels the surface presented. */
+type LoupeMode = 'vector' | 'pixel';
+/**
+ * What a loupe needs from the surface it magnifies. A painter implements it,
+ * and the model asks nothing about how the lens is drawn — only where it is,
+ * what colour is under a point, and whether anyone can still see it.
+ */
+interface LoupeSurface {
+    /** The lens' rectangle, or `null` while it has none. */
+    lens(): LoupeRect | null;
+    /**
+     * Does the lens itself cover this point? A stationary lens does over its own
+     * frame, which is what the freeze rule below is for; a lens that follows the
+     * pointer never covers it and answers `false`.
+     */
+    covers(p: LoupePoint): boolean;
+    /** Hex colour at a surface point, or `null` when the surface cannot say. */
+    sample(p: LoupePoint): string | null;
+    /** Is the lens off screen? Aims are ignored while it is. */
+    hidden(): boolean;
+    /** Is the lens gone for good? The model tears itself down when it is. */
+    gone(): boolean;
+    /** Something the painter must redraw for has changed. */
+    changed(): void;
+}
+/** Options for {@link createLoupeModel}. */
+interface LoupeModelOptions {
+    surface: LoupeSurface;
+    mode?: LoupeMode;
+    /** Magnification. Default 8. */
+    factor?: number;
+    /** Bounds `setFactor` clamps to. Unset means unclamped. */
+    minFactor?: number;
+    maxFactor?: number;
+    /** Called with the hex colour under the aim point whenever it changes. */
+    onColorChange?: (hex: string) => void;
+    /** Called when a pick lands — an eyedropper on the magnified surface. Where
+     *  the colour goes is the consumer's business. */
+    onPick?: (hex: string) => void;
+    /** Called when the model tears itself down because the surface reported the
+     *  lens gone, so the painter can drop what it was holding. */
+    onDispose?: () => void;
+}
+/** Where a loupe is aimed, how far it magnifies, and what colour it is over. */
+interface LoupeModel {
+    readonly mode: LoupeMode;
+    readonly factor: number;
+    /** Last aimed point, in the surface's CSS px. */
+    readonly aim: LoupePoint;
+    /** Hex colour under the aim point. `null` until something answers. */
+    readonly color: string | null;
+    setMode(mode: LoupeMode): void;
+    setFactor(factor: number): void;
+    /** Aim at a surface point. Ignored while the lens covers it, is hidden, or
+     *  the model is disposed. */
+    aimAt(p: LoupePoint): void;
+    /** Sample what the lens shows at `p`, a point inside it, and report that to
+     *  `onPick`. Omit `p` to pick at the aim point. Leaves the aim, and `color`,
+     *  alone. */
+    pick(p?: LoupePoint): string | null;
+    dispose(): void;
+}
+/**
+ * Build the loupe's model over a surface. It holds the state a magnifier has —
+ * aim, factor, mode, colour — and none of the drawing.
+ */
+declare function createLoupeModel(opts: LoupeModelOptions): LoupeModel;
+
+export { type LoupeMode, type LoupeModel, type LoupeModelOptions, type LoupePoint, type LoupeRect, type LoupeSurface, createLoupeModel, loupeInnerView, loupeSourcePoint };

package/dist/index.js

@@ -0,0 +1,94 @@
+// src/geometry.ts
+function loupeInnerView(target, outer, rect, factor) {
+  const scale = { x: outer.scale.x * factor, y: outer.scale.y * factor };
+  return {
+    x: target.x - rect.w / 2 / scale.x,
+    y: target.y - rect.h / 2 / scale.y,
+    scale
+  };
+}
+function loupeSourcePoint(p, rect, aim, factor) {
+  return {
+    x: aim.x + (p.x - (rect.x + rect.w / 2)) / factor,
+    y: aim.y + (p.y - (rect.y + rect.h / 2)) / factor
+  };
+}
+
+// src/model.ts
+function createLoupeModel(opts) {
+  const { surface } = opts;
+  let mode = opts.mode ?? "vector";
+  let factor = opts.factor ?? 8;
+  let aim = { x: 0, y: 0 };
+  let color = null;
+  let disposed = false;
+  const clamp = (n) => Math.min(
+    opts.maxFactor ?? Number.POSITIVE_INFINITY,
+    Math.max(opts.minFactor ?? Number.NEGATIVE_INFINITY, n)
+  );
+  const teardown = () => {
+    if (disposed) return;
+    disposed = true;
+    opts.onDispose?.();
+  };
+  const sampleColor = () => {
+    const hex = surface.sample(aim);
+    if (hex === null || hex === color) return;
+    color = hex;
+    opts.onColorChange?.(hex);
+  };
+  return {
+    get mode() {
+      return mode;
+    },
+    get factor() {
+      return factor;
+    },
+    get aim() {
+      return aim;
+    },
+    get color() {
+      return color;
+    },
+    setMode(next) {
+      if (disposed || next === mode) return;
+      mode = next;
+      surface.changed();
+    },
+    setFactor(next) {
+      if (disposed) return;
+      factor = clamp(next);
+      surface.changed();
+    },
+    aimAt(p) {
+      if (disposed) return;
+      if (surface.gone()) {
+        teardown();
+        return;
+      }
+      if (surface.hidden()) return;
+      if (surface.covers(p)) return;
+      aim = p;
+      sampleColor();
+      surface.changed();
+    },
+    pick(p) {
+      if (disposed) return null;
+      let at = aim;
+      if (p) {
+        const rect = surface.lens();
+        if (!rect) return null;
+        at = loupeSourcePoint(p, rect, aim, factor);
+        if (surface.covers(at)) return null;
+      }
+      const hex = surface.sample(at);
+      if (hex !== null) opts.onPick?.(hex);
+      return hex;
+    },
+    dispose: teardown
+  };
+}
+
+export { createLoupeModel, loupeInnerView, loupeSourcePoint };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/geometry.ts","../src/model.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { View } from '@weasel-js/core';\n\n/** A point on the magnified surface, in its own CSS pixels. */\nexport interface LoupePoint {\n  x: number;\n  y: number;\n}\n\n/** The lens' rectangle on that surface. */\nexport interface LoupeRect extends LoupePoint {\n  w: number;\n  h: number;\n}\n\n/**\n * The inner `View` a loupe renders its content through: the outer view's\n * magnification times `factor`, positioned so `target` sits at the center of\n * a viewport the size of `rect`.\n */\nexport function loupeInnerView(\n  target: LoupePoint,\n  outer: View,\n  rect: LoupeRect,\n  factor: number,\n): View {\n  const scale = { x: outer.scale.x * factor, y: outer.scale.y * factor };\n  return {\n    x: target.x - rect.w / 2 / scale.x,\n    y: target.y - rect.h / 2 / scale.y,\n    scale,\n  };\n}\n\n/**\n * Where on the outer surface a point inside the lens is looking, in\n * screen-space CSS px.\n *\n * The inverse of {@link loupeInnerView}: the lens centers `aim` in `rect` and\n * magnifies by `factor`, and the outer view's own scale cancels out of the\n * round trip — so this needs no `View`.\n */\nexport function loupeSourcePoint(\n  p: LoupePoint,\n  rect: LoupeRect,\n  aim: LoupePoint,\n  factor: number,\n): LoupePoint {\n  return {\n    x: aim.x + (p.x - (rect.x + rect.w / 2)) / factor,\n    y: aim.y + (p.y - (rect.y + rect.h / 2)) / factor,\n  };\n}\n","import { type LoupePoint, type LoupeRect, loupeSourcePoint } from './geometry';\n\n/** How a loupe magnifies. `'vector'` re-renders the source through a zoomed-in\n *  view, so content stays sharp at any factor; `'pixel'` blows up the actual\n *  pixels the surface presented. */\nexport type LoupeMode = 'vector' | 'pixel';\n\n/**\n * What a loupe needs from the surface it magnifies. A painter implements it,\n * and the model asks nothing about how the lens is drawn — only where it is,\n * what colour is under a point, and whether anyone can still see it.\n */\nexport interface LoupeSurface {\n  /** The lens' rectangle, or `null` while it has none. */\n  lens(): LoupeRect | null;\n  /**\n   * Does the lens itself cover this point? A stationary lens does over its own\n   * frame, which is what the freeze rule below is for; a lens that follows the\n   * pointer never covers it and answers `false`.\n   */\n  covers(p: LoupePoint): boolean;\n  /** Hex colour at a surface point, or `null` when the surface cannot say. */\n  sample(p: LoupePoint): string | null;\n  /** Is the lens off screen? Aims are ignored while it is. */\n  hidden(): boolean;\n  /** Is the lens gone for good? The model tears itself down when it is. */\n  gone(): boolean;\n  /** Something the painter must redraw for has changed. */\n  changed(): void;\n}\n\n/** Options for {@link createLoupeModel}. */\nexport interface LoupeModelOptions {\n  surface: LoupeSurface;\n  mode?: LoupeMode;\n  /** Magnification. Default 8. */\n  factor?: number;\n  /** Bounds `setFactor` clamps to. Unset means unclamped. */\n  minFactor?: number;\n  maxFactor?: number;\n  /** Called with the hex colour under the aim point whenever it changes. */\n  onColorChange?: (hex: string) => void;\n  /** Called when a pick lands — an eyedropper on the magnified surface. Where\n   *  the colour goes is the consumer's business. */\n  onPick?: (hex: string) => void;\n  /** Called when the model tears itself down because the surface reported the\n   *  lens gone, so the painter can drop what it was holding. */\n  onDispose?: () => void;\n}\n\n/** Where a loupe is aimed, how far it magnifies, and what colour it is over. */\nexport interface LoupeModel {\n  readonly mode: LoupeMode;\n  readonly factor: number;\n  /** Last aimed point, in the surface's CSS px. */\n  readonly aim: LoupePoint;\n  /** Hex colour under the aim point. `null` until something answers. */\n  readonly color: string | null;\n  setMode(mode: LoupeMode): void;\n  setFactor(factor: number): void;\n  /** Aim at a surface point. Ignored while the lens covers it, is hidden, or\n   *  the model is disposed. */\n  aimAt(p: LoupePoint): void;\n  /** Sample what the lens shows at `p`, a point inside it, and report that to\n   *  `onPick`. Omit `p` to pick at the aim point. Leaves the aim, and `color`,\n   *  alone. */\n  pick(p?: LoupePoint): string | null;\n  dispose(): void;\n}\n\n/**\n * Build the loupe's model over a surface. It holds the state a magnifier has —\n * aim, factor, mode, colour — and none of the drawing.\n */\nexport function createLoupeModel(opts: LoupeModelOptions): LoupeModel {\n  const { surface } = opts;\n  let mode: LoupeMode = opts.mode ?? 'vector';\n  let factor = opts.factor ?? 8;\n  let aim: LoupePoint = { x: 0, y: 0 };\n  let color: string | null = null;\n  let disposed = false;\n\n  const clamp = (n: number): number =>\n    Math.min(opts.maxFactor ?? Number.POSITIVE_INFINITY,\n             Math.max(opts.minFactor ?? Number.NEGATIVE_INFINITY, n));\n\n  const teardown = () => {\n    if (disposed) return;\n    disposed = true;\n    opts.onDispose?.();\n  };\n\n  const sampleColor = () => {\n    const hex = surface.sample(aim);\n    if (hex === null || hex === color) return;\n    color = hex;\n    opts.onColorChange?.(hex);\n  };\n\n  return {\n    get mode() { return mode; },\n    get factor() { return factor; },\n    get aim() { return aim; },\n    get color() { return color; },\n\n    setMode(next) {\n      if (disposed || next === mode) return;\n      mode = next;\n      surface.changed();\n    },\n\n    setFactor(next) {\n      if (disposed) return;\n      factor = clamp(next);\n      surface.changed();\n    },\n\n    aimAt(p) {\n      if (disposed) return;\n      // A lens can be taken away by whatever owns it, without coming back\n      // through `dispose`. Follow it down rather than keep sampling for a\n      // magnifier nobody can see.\n      if (surface.gone()) { teardown(); return; }\n      if (surface.hidden()) return;\n      if (surface.covers(p)) return;\n      aim = p;\n      sampleColor();\n      surface.changed();\n    },\n\n    pick(p) {\n      if (disposed) return null;\n      let at = aim;\n      if (p) {\n        const rect = surface.lens();\n        if (!rect) return null;\n        at = loupeSourcePoint(p, rect, aim, factor);\n        // The lens is part of the picture the surface presents. A point near\n        // its frame maps back underneath it, and sampling there reports the\n        // lens' own chrome as artwork.\n        if (surface.covers(at)) return null;\n      }\n      const hex = surface.sample(at);\n      if (hex !== null) opts.onPick?.(hex);\n      return hex;\n    },\n\n    dispose: teardown,\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@weasel-js/loupe",
+  "version": "1.4.0-pre.0",
+  "description": "Surface-free magnifier model: where a loupe is aimed, how far it magnifies, and what colour it is over. Painters live with the surfaces they draw on.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "author": "orochi235",
+  "homepage": "https://orochi235.github.io/weasel/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orochi235/weasel.git",
+    "directory": "packages/loupe"
+  },
+  "bugs": {
+    "url": "https://github.com/orochi235/weasel/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@weasel-js/core": "1.4.0-pre.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}