@cesarvenzac/closeup 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 César Venzac
+
+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

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# @cesarvenzac/closeup
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Film any part of a web page in close-up, sharp at any size: photos and videos of an element or
+a region, with a drawn macOS-like cursor that follows your mouse or plays a path you draw, on a
+background, with click sounds.
+
+```sh
+npm install @cesarvenzac/closeup
+```
+
+## Use
+
+```ts
+import { install } from "@cesarvenzac/closeup";
+
+install(); // ⌥⇧C opens and closes it
+```
+
+Or load it only when it's wanted, on a shortcut of your own:
+
+```ts
+addEventListener("keydown", (event) => {
+  if (event.code === "KeyC" && event.altKey && event.shiftKey) import("@cesarvenzac/closeup").then((closeup) => closeup.toggle());
+});
+```
+
+Press the shortcut, point at an element (↑ and ↓ widen and narrow the pick) or draw a region,
+choose a photo or a video, and press Record. Chrome asks once to share the tab. Options set the
+shape (16:9, 1:1, 4:5, 9:16 or the pick's own), the room round the pick, a background (a colour,
+a gradient or an image of your own) with inset, corners and shadow, the cursor, its click ring,
+the sounds and the quality. They're kept in the browser.
+
+## Scripts
+
+The pen button (video only) opens the script editor on the stage, at the size the take is filmed:
+
+- Click where the cursor starts, then each place it goes. A click makes a gentle arc, as a wrist
+  moves; a drag pulls the curve's handles, as Figma's pen does. Drag points and handles to adjust
+  them, ⌥ to break a handle's mirror, double-click a point to switch between handles and an arc.
+- Each point moves there, clicks or types, after hovering a moment if you like, then rests. The
+  pace is a hand's (Fitts's law, with minimum-jerk speed) unless you set it. Type clicks the point
+  and types into the text field that click focused, a character at a time: put it on a field.
+- A point is tied to the element it's placed on, so it follows that element if the layout moves.
+- Preview plays it on the page without filming. Done saves it for this page and sets Moves to
+  Script, so Record plays it and stops by itself. Undo, redo, import and export are in the bar.
+
+While a script plays, the page is told about every move and press as a mouse would tell it
+(pointer and mouse events, focus), so its own code reacts: hover effects, menus, a character that
+turns to look. CSS's `:hover` and `:active` only follow the real pointer, so every rule that uses
+them is copied with an attribute in their place, and the attribute is set on what the cursor is
+over. Your mouse is kept off the page meanwhile.
+
+A script is plain JSON:
+
+```json
+{
+  "version": 1,
+  "start": { "x": 480, "y": 130 },
+  "steps": [
+    {
+      "to": { "x": 450, "y": 110, "on": { "selector": "button.like", "u": 0.5, "v": 0.5 } },
+      "action": "click",
+      "hover": 0.4,
+      "wait": 1
+    },
+    { "to": { "x": 600, "y": 300 }, "action": "type", "text": "Hello", "wait": 0.6 }
+  ]
+}
+```
+
+Points are in page pixels (as laid out, not enlarged); `on` names the element and where in its box
+(0 to 1). Handles (`in`, `out`) are optional, relative to their point.
+
+## Your own actions
+
+`addAction` puts a button of your own on the finished take, beside Download, to keep it somewhere:
+
+```ts
+import { addAction } from "@cesarvenzac/closeup";
+
+addAction({
+  label: "Save to library",
+  icon: `<path d="M12 13v8"/><path d="m8 17 4-4 4 4"/>`, // optional: paths on a 24-unit grid
+  when: (take) => take.kind === "video", // optional: which takes to offer it on
+  async run(take, { progress }) {
+    // take.blob, take.type, take.width, take.height, take.seconds, take.script
+    await upload(take.blob, progress); // call progress(0…1) as it goes
+    return "Saved."; // said when it's done; a thrown error's message is said instead
+  },
+});
+```
+
+The button counts up while it works and stays pressed once it's done. `addAction` returns what
+takes it away again.
+
+## How it stays sharp
+
+A capture of a small part of the screen is small: a 120-pixel button filmed and enlarged is a
+blur. Closeup enlarges the page first. A transform on `<body>` scales it round the pick until the
+pick fills the window, so the browser draws it large at the screen's full resolution; the layout
+doesn't change, only how big it's drawn. The tab is then captured (`getDisplayMedia`) and cropped
+to the frame by Region Capture (`CropTarget`, `cropTo`), so Closeup's own controls, outside the
+frame, never show. The real cursor would be drawn into the capture small and soft, so it's hidden
+and a drawn one stands in. The frames are laid on their background in a canvas and recorded.
+
+## Needs
+
+A Chromium browser on a desktop (Chrome, Edge, Arc, Brave): Region Capture is Chromium's. Chrome
+records H.264 MP4; other builds may record WebM. Styles from another site's stylesheets can't be
+read, so their hover rules can't be copied; code that checks `event.isTrusted` ignores a script's
+events. The page doesn't scroll during a take.
+
+## Development
+
+```sh
+npm ci
+npm test
+npm run typecheck
+npm run check # packed as npm publishes it, then installed and run as a user's would be
+```
+
+This repository is a copy. The package is developed inside the site it was made for, whose
+repository is private, and every release copies it here and publishes it to npm from here, with
+provenance. Issues are welcome; pull requests are read, and their changes made at the source.
+
+## Licence
+
+MIT

package/dist/actions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Actions of your own on a finished take: buttons on the take's sheet, beside Download, that hand
+ * the take to your code (to keep it in a library, send it somewhere, …). Closeup shows the button,
+ * its progress while it runs, and what it says when it's done or fails.
+ */
+import type { Result } from "./take.ts";
+/** A finished take: the file, its size, its length, and the script it played if one did. */
+export type Take = Result;
+export type TakeAction = {
+    /** The button's words, e.g. "Save to library". */
+    label: string;
+    /** An icon beside them: the inside of an SVG on a 24-unit grid, drawn with Closeup's stroke (Lucide's paths fit). */
+    icon?: string;
+    /** Offered for this take? Every take when left out. */
+    when?: (take: Take) => boolean;
+    /**
+     * Does the work. Call `progress` with 0 to 1 as it goes; what it resolves to is said when it's
+     * done ("Saved." when nothing), and a thrown error's message is said instead.
+     */
+    run: (take: Take, context: {
+        progress: (done: number) => void;
+    }) => Promise<string | void>;
+};
+/** Offers `action` on every take from now on. Returns what takes it away. */
+export declare function addAction(action: TakeAction): () => undefined;
+/** The actions offered for a take, in the order they were added. */
+export declare const actionsFor: (take: Take) => TakeAction[];

package/dist/actions.js

@@ -0,0 +1,13 @@
+/**
+ * Actions of your own on a finished take: buttons on the take's sheet, beside Download, that hand
+ * the take to your code (to keep it in a library, send it somewhere, …). Closeup shows the button,
+ * its progress while it runs, and what it says when it's done or fails.
+ */
+const registered = new Set();
+/** Offers `action` on every take from now on. Returns what takes it away. */
+export function addAction(action) {
+    registered.add(action);
+    return () => void registered.delete(action);
+}
+/** The actions offered for a take, in the order they were added. */
+export const actionsFor = (take) => [...registered].filter((action) => action.when?.(take) ?? true);

package/dist/capture.d.ts

@@ -0,0 +1,28 @@
+/**
+ * This tab as a video track, cropped to one element by Region Capture: what's on screen inside
+ * the element's box, exactly as drawn (3D canvases and video included), and nothing else, so
+ * Closeup's own controls outside it never show. Chromium only, for now.
+ */
+type CropTargetLike = object;
+type CroppableTrack = MediaStreamTrack & {
+    cropTo(target: CropTargetLike | null): Promise<void>;
+};
+/** Whether this browser can share a tab and crop it to an element (cropTo lives on the captured track's own class). */
+export declare const supportsCapture: () => boolean;
+/**
+ * Asks to share this tab. Must run in the click that asked for it: browsers refuse a capture
+ * started without a gesture. `audio` offers the tab's own sound too (Chrome shows a checkbox).
+ */
+export declare function shareTab({ audio, frameRate }: {
+    audio: boolean;
+    frameRate?: number;
+}): Promise<{
+    stream: MediaStream;
+    video: CroppableTrack;
+    audio: MediaStreamTrack;
+}>;
+/** Crops the captured tab to `element`'s box, wherever it is on screen. */
+export declare function cropTo(track: MediaStreamTrack, element: Element): Promise<void>;
+/** Crops again from scratch: a capture cropped as it starts can stay silent, and this wakes it. */
+export declare function recrop(track: MediaStreamTrack, element: Element): Promise<void>;
+export {};

package/dist/capture.js

@@ -0,0 +1,33 @@
+/**
+ * This tab as a video track, cropped to one element by Region Capture: what's on screen inside
+ * the element's box, exactly as drawn (3D canvases and video included), and nothing else, so
+ * Closeup's own controls outside it never show. Chromium only, for now.
+ */
+/** Whether this browser can share a tab and crop it to an element (cropTo lives on the captured track's own class). */
+export const supportsCapture = () => typeof navigator !== "undefined" && !!navigator.mediaDevices?.getDisplayMedia && typeof CropTarget !== "undefined";
+/**
+ * Asks to share this tab. Must run in the click that asked for it: browsers refuse a capture
+ * started without a gesture. `audio` offers the tab's own sound too (Chrome shows a checkbox).
+ */
+export async function shareTab({ audio, frameRate = 60 }) {
+    const stream = await navigator.mediaDevices.getDisplayMedia({
+        // As large as the tab's real pixels: the crop is taken from these.
+        video: { frameRate: { ideal: frameRate, max: frameRate }, width: { ideal: 8192 }, height: { ideal: 8192 } },
+        audio,
+        // Not standard everywhere yet; Chrome reads them.
+        ...{ preferCurrentTab: true, selfBrowserSurface: "include", systemAudio: "exclude" },
+    });
+    const [video] = stream.getVideoTracks();
+    return { stream, video: video, audio: stream.getAudioTracks()[0] ?? null };
+}
+/** Crops the captured tab to `element`'s box, wherever it is on screen. */
+export async function cropTo(track, element) {
+    if (typeof CropTarget === "undefined")
+        throw new Error("This browser can't crop a capture (Region Capture is Chromium's)");
+    await track.cropTo(await CropTarget.fromElement(element));
+}
+/** Crops again from scratch: a capture cropped as it starts can stay silent, and this wakes it. */
+export async function recrop(track, element) {
+    await track.cropTo(null);
+    await cropTo(track, element);
+}

package/dist/compositor.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Draws each captured frame onto a canvas, alone or set on a background (a colour, a gradient
+ * or a picture) with room round it, rounded corners and a soft shadow, and gives the canvas
+ * back as a video track, one canvas frame per captured frame. Sizes are the capture's own
+ * pixels, so nothing is enlarged.
+ */
+export type Background = {
+    kind: "none";
+} | {
+    kind: "color";
+    color: string;
+} | {
+    kind: "gradient";
+    from: string;
+    to: string;
+    angle: number;
+} | {
+    kind: "image";
+    image: ImageBitmap;
+};
+export type Look = {
+    background: Background;
+    /** Room between the take's edge and the page, a share of its shorter side (with a background only). */
+    inset: number;
+    /** Corner radius of the page on its background, in pixels at 1080p (with a background only). */
+    radius: number;
+    shadow: boolean;
+};
+export declare class Compositor {
+    private readonly input;
+    private readonly look;
+    /** Where the hidden video playing the capture lives: outside the page's <body>. */
+    private readonly host;
+    readonly canvas: HTMLCanvasElement;
+    private readonly context;
+    private readonly video;
+    private output;
+    private callback;
+    private stopped;
+    constructor(input: MediaStreamTrack, look: Look, 
+    /** Where the hidden video playing the capture lives: outside the page's <body>. */
+    host: Element);
+    /**
+     * Starts once the first frame arrives (it sets the size) and resolves with the composed track.
+     * A tab sends a frame only when something in it repaints, and a capture cropped as it starts
+     * can stay silent, so until the first frame `nudge` is called every animation frame (it should
+     * repaint something in the frame, unseen) and `wake` every half second (it should crop again).
+     */
+    start({ nudge, wake }: Waking): Promise<MediaStreamTrack>;
+    get size(): {
+        width: number;
+        height: number;
+    };
+    /** The composed frame now, as a PNG. */
+    snapshot(): Promise<Blob>;
+    stop(): void;
+    private draw;
+}
+export type Waking = {
+    nudge: () => void;
+    wake: () => Promise<unknown>;
+};

package/dist/compositor.js

@@ -0,0 +1,164 @@
+/**
+ * Draws each captured frame onto a canvas, alone or set on a background (a colour, a gradient
+ * or a picture) with room round it, rounded corners and a soft shadow, and gives the canvas
+ * back as a video track, one canvas frame per captured frame. Sizes are the capture's own
+ * pixels, so nothing is enlarged.
+ */
+import { insetRect } from "./frame.js";
+export class Compositor {
+    input;
+    look;
+    host;
+    canvas = document.createElement("canvas");
+    context = this.canvas.getContext("2d", { alpha: false });
+    video = document.createElement("video");
+    output = null;
+    callback = 0;
+    stopped = false;
+    constructor(input, look, 
+    /** Where the hidden video playing the capture lives: outside the page's <body>. */
+    host) {
+        this.input = input;
+        this.look = look;
+        this.host = host;
+    }
+    /**
+     * Starts once the first frame arrives (it sets the size) and resolves with the composed track.
+     * A tab sends a frame only when something in it repaints, and a capture cropped as it starts
+     * can stay silent, so until the first frame `nudge` is called every animation frame (it should
+     * repaint something in the frame, unseen) and `wake` every half second (it should crop again).
+     */
+    async start({ nudge, wake }) {
+        const video = this.video;
+        video.muted = true;
+        video.playsInline = true;
+        video.srcObject = new MediaStream([this.input]);
+        // Laid out but unseen, so the browser keeps decoding it.
+        Object.assign(video.style, { position: "fixed", left: "0", top: "0", width: "2px", height: "2px", opacity: "0", pointerEvents: "none" });
+        this.host.append(video);
+        const playing = video.play();
+        await firstFrame(video, nudge, wake);
+        await playing;
+        this.canvas.width = video.videoWidth;
+        this.canvas.height = video.videoHeight;
+        this.output = this.canvas.captureStream(0).getVideoTracks()[0];
+        this.draw();
+        const loop = () => {
+            if (this.stopped)
+                return;
+            this.draw();
+            this.output?.requestFrame();
+            this.callback = video.requestVideoFrameCallback(loop);
+        };
+        this.callback = video.requestVideoFrameCallback(loop);
+        return this.output;
+    }
+    get size() {
+        return { width: this.canvas.width, height: this.canvas.height };
+    }
+    /** The composed frame now, as a PNG. */
+    snapshot() {
+        this.draw();
+        return new Promise((resolve, reject) => this.canvas.toBlob((blob) => (blob ? resolve(blob) : reject(new Error("No frame"))), "image/png"));
+    }
+    stop() {
+        this.stopped = true;
+        this.video.cancelVideoFrameCallback?.(this.callback);
+        this.output?.stop();
+        this.video.srcObject = null;
+        this.video.remove();
+    }
+    draw() {
+        const { context: c, canvas, video, look } = this;
+        const { width, height } = canvas;
+        if (!width || video.readyState < 2)
+            return;
+        if (look.background.kind === "none") {
+            c.drawImage(video, 0, 0, width, height);
+            return;
+        }
+        paintBackground(c, look.background, width, height);
+        const inner = insetRect({ width, height }, look.inset);
+        const unit = Math.min(width, height) / 1080;
+        const radius = look.radius * unit;
+        if (look.shadow) {
+            c.save();
+            c.shadowColor = "rgb(0 0 0 / 0.28)";
+            c.shadowBlur = 48 * unit;
+            c.shadowOffsetY = 16 * unit;
+            c.fillStyle = "#000";
+            c.beginPath();
+            c.roundRect(inner.x, inner.y, inner.width, inner.height, radius);
+            c.fill();
+            c.restore();
+        }
+        c.save();
+        c.beginPath();
+        c.roundRect(inner.x, inner.y, inner.width, inner.height, radius);
+        c.clip();
+        c.drawImage(video, inner.x, inner.y, inner.width, inner.height);
+        c.restore();
+    }
+}
+function paintBackground(c, background, width, height) {
+    if (background.kind === "color") {
+        c.fillStyle = background.color;
+        c.fillRect(0, 0, width, height);
+    }
+    else if (background.kind === "gradient") {
+        const angle = (background.angle * Math.PI) / 180;
+        const half = (Math.abs(width * Math.sin(angle)) + Math.abs(height * Math.cos(angle))) / 2;
+        const [dx, dy] = [Math.sin(angle) * half, -Math.cos(angle) * half];
+        const gradient = c.createLinearGradient(width / 2 - dx, height / 2 - dy, width / 2 + dx, height / 2 + dy);
+        gradient.addColorStop(0, background.from);
+        gradient.addColorStop(1, background.to);
+        c.fillStyle = gradient;
+        c.fillRect(0, 0, width, height);
+    }
+    else if (background.kind === "image") {
+        // Cover: the picture fills the take, cropped evenly on the long side.
+        const { image } = background;
+        const scale = Math.max(width / image.width, height / image.height);
+        const w = image.width * scale;
+        const h = image.height * scale;
+        c.drawImage(image, (width - w) / 2, (height - h) / 2, w, h);
+    }
+}
+/** How long a capture may take to send its first picture before the take gives up, and how often it's woken meanwhile. */
+const FIRST_FRAME_MS = 5000;
+const WAKE_MS = 500;
+function firstFrame(video, nudge, wake) {
+    return new Promise((resolve, reject) => {
+        let done = false;
+        let frame = 0;
+        const started = performance.now();
+        const end = () => {
+            done = true;
+            cancelAnimationFrame(frame);
+        };
+        video.requestVideoFrameCallback(() => {
+            end();
+            resolve();
+        });
+        const tick = () => {
+            if (done)
+                return;
+            nudge();
+            frame = requestAnimationFrame(tick);
+        };
+        tick();
+        void (async () => {
+            while (!done) {
+                await new Promise((next) => setTimeout(next, WAKE_MS));
+                if (done)
+                    return;
+                if (performance.now() - started > FIRST_FRAME_MS) {
+                    end();
+                    reject(new Error("the tab sent no picture"));
+                    return;
+                }
+                await wake().catch(() => undefined);
+            }
+        })();
+    });
+}

package/dist/cursor.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A drawn cursor in place of the real one while a take lasts. Chrome adds the real cursor to a
+ * tab capture as a small, soft picture laid on top, which stage mode can't sharpen; this one is
+ * drawn by the page at the screen's full resolution. It takes the shape the real one would
+ * have there (the hand over links and buttons, the I-beam over text, else the arrow) and
+ * presses a little on a click. It lives outside <body>, so stage mode doesn't enlarge it.
+ */
+export type CursorOptions = {
+    /** How big it's drawn, in CSS pixels across its 24-unit box. */
+    size: number;
+    /** Each press and release, for the click sound. */
+    onPress?: (down: boolean) => void;
+    /** A soft ring that spreads from the tip on each click, so a viewer sees it. */
+    ring?: boolean;
+    /** Events over Closeup's own controls: the real cursor shows there, the drawn one hides. */
+    ignore?: (target: EventTarget | null) => boolean;
+    /** The page's element at a point, Closeup's own layers left out. */
+    hit: (x: number, y: number) => Element | null;
+    /** Where a caret would go at a point, Closeup's own layers left out (to tell text from space). */
+    caretAt?: (x: number, y: number) => Range | null;
+};
+export declare class DrawnCursor {
+    private readonly host;
+    private readonly options;
+    private readonly element;
+    private readonly hide;
+    private shape;
+    private shown;
+    private x;
+    private y;
+    constructor(host: Element, options: CursorOptions);
+    /** Puts it on the page, hiding the real cursor there; it appears at its first `place`. */
+    show(): void;
+    /** Follows the real pointer. */
+    follow(): void;
+    destroy(): void;
+    /** Draws it at a point on screen, in the shape the real cursor would take there. */
+    place(x: number, y: number): void;
+    /** Presses a little going down, and back coming up, with the click's sound (and the ring, going down). */
+    press(down: boolean): void;
+    /** The ring: from the tip, out to about the cursor's size, fading as it goes. Still under reduced motion. */
+    private ripple;
+    private onMove;
+    private onDown;
+    private onUp;
+    private onLeave;
+    /** The shape the real cursor would take here: read with the hiding rule off for a moment. */
+    private shapeAt;
+}