@vitrinka/link 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @vitrinka/link
 
+## 0.1.2
+
+- **`@vitrinka/link/dock`.** The recorder HUD's snap math, shared by the
+  web and Expo recorders: `settle` (six spots, velocity-projected flick,
+  side-edge tuck), `spotRect`, `neighbour` (arrow keys), `untuck`,
+  `parsePlace` (validated stored position).
+
 ## 0.1.1
 
 - **Workspace hint.** `linkWorkspace(base)` reads the `<slug>` of a

package/README.md

@@ -29,3 +29,17 @@ A token only authenticates in the workspace it was approved into, so a
 URLs as a `workspace=<slug>` preselect (never the start body), and a claim
 approved into another workspace rejects with `LinkWorkspaceMismatch`
 (`linked`, `expected`, a ready-to-show message) — the token is discarded.
+
+## Dock (`@vitrinka/link/dock`)
+
+Where a recorder HUD may rest, shared by every recorder so a throw lands the
+same way everywhere: six spots (corners plus top and bottom centre), a
+release projected along its velocity, and a tuck into a side-edge tab when
+more than a third of the HUD is pushed past that edge. Pure numbers.
+
+```ts
+import { settle, neighbour, parsePlace, spotRect } from '@vitrinka/link/dock';
+
+settle(releasedRect, { x: vx, y: vy }, viewport, insets); // { spot: 'tr' } | { tuck: 'right', y: 0.4 }
+neighbour({ spot: 'br' }, 'ArrowLeft');                   // { spot: 'bc' } — the keyboard alternative
+```

package/build/dock.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @vitrinka/link/dock — where a recorder HUD may rest, shared by every
+ * recorder (web, Expo, the extension's port) so a throw lands the same way
+ * everywhere.
+ *
+ * Six spots — the four corners plus top and bottom centre. A release is
+ * projected along its velocity (iOS picture-in-picture: a flick lands where
+ * it is aimed, not merely nearest) and settles on the spot closest to the
+ * projected centre. A release with more than a third of the HUD pushed past
+ * a side edge tucks it into a tab on that edge instead, at the height it was
+ * dropped. Pure numbers: no DOM, no React Native.
+ */
+export type Spot = 'tl' | 'tc' | 'tr' | 'bl' | 'bc' | 'br';
+export type Side = 'left' | 'right';
+/** Where the HUD rests: a spot, or tucked into a side edge at `y` (0 top … 1 bottom). */
+export type Place = {
+    spot: Spot;
+} | {
+    tuck: Side;
+    y: number;
+};
+export interface Size {
+    w: number;
+    h: number;
+}
+export interface Rect extends Size {
+    x: number;
+    y: number;
+}
+/** Distance from the viewport edges, safe-area insets already added. */
+export interface Insets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export declare const SPOTS: readonly Spot[];
+export declare const DEFAULT_PLACE: Place;
+/** Seconds of travel a release is projected along its velocity. */
+export declare const FLICK_PROJECTION_S = 0.3;
+/** Fraction of the HUD's width past a side edge that tucks it. */
+export declare const TUCK_FRACTION: number;
+export declare function rowOf(spot: Spot): 't' | 'b';
+export declare function colOf(spot: Spot): 'l' | 'c' | 'r';
+/** The rect a HUD of `size` occupies when resting at `spot`. */
+export declare function spotRect(spot: Spot, size: Size, view: Size, inset: Insets): Rect;
+/**
+ * Where a released HUD settles. `rect` is where it was let go (viewport
+ * px), `velocity` the pointer's px/s at release.
+ */
+export declare function settle(rect: Rect, velocity: {
+    x: number;
+    y: number;
+}, view: Size, inset: Insets): Place;
+/** The spot a tucked HUD returns to: the nearer corner on its side. */
+export declare function untuck(place: Place): Spot;
+export type Arrow = 'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'ArrowDown';
+/** The spot an arrow key moves to — the keyboard alternative to dragging. */
+export declare function neighbour(place: Place, arrow: Arrow): Place;
+/** A stored place, validated; anything else is the default. */
+export declare function parsePlace(raw: unknown): Place;

package/build/dock.js

@@ -0,0 +1,101 @@
+/**
+ * @vitrinka/link/dock — where a recorder HUD may rest, shared by every
+ * recorder (web, Expo, the extension's port) so a throw lands the same way
+ * everywhere.
+ *
+ * Six spots — the four corners plus top and bottom centre. A release is
+ * projected along its velocity (iOS picture-in-picture: a flick lands where
+ * it is aimed, not merely nearest) and settles on the spot closest to the
+ * projected centre. A release with more than a third of the HUD pushed past
+ * a side edge tucks it into a tab on that edge instead, at the height it was
+ * dropped. Pure numbers: no DOM, no React Native.
+ */
+export const SPOTS = ['tl', 'tc', 'tr', 'bl', 'bc', 'br'];
+export const DEFAULT_PLACE = { spot: 'br' };
+/** Seconds of travel a release is projected along its velocity. */
+export const FLICK_PROJECTION_S = 0.3;
+/** Fraction of the HUD's width past a side edge that tucks it. */
+export const TUCK_FRACTION = 1 / 3;
+export function rowOf(spot) {
+    return spot[0];
+}
+export function colOf(spot) {
+    return spot[1];
+}
+/** The rect a HUD of `size` occupies when resting at `spot`. */
+export function spotRect(spot, size, view, inset) {
+    const col = colOf(spot);
+    const x = col === 'l' ? inset.left : col === 'r' ? view.w - inset.right - size.w : (view.w - size.w) / 2;
+    const y = rowOf(spot) === 't' ? inset.top : view.h - inset.bottom - size.h;
+    return { x, y, w: size.w, h: size.h };
+}
+/**
+ * Where a released HUD settles. `rect` is where it was let go (viewport
+ * px), `velocity` the pointer's px/s at release.
+ */
+export function settle(rect, velocity, view, inset) {
+    const past = Math.max(-rect.x, rect.x + rect.w - view.w);
+    if (past > rect.w * TUCK_FRACTION) {
+        const side = -rect.x > rect.x + rect.w - view.w ? 'left' : 'right';
+        return { tuck: side, y: clamp01((rect.y + rect.h / 2) / Math.max(1, view.h)) };
+    }
+    const px = rect.x + rect.w / 2 + velocity.x * FLICK_PROJECTION_S;
+    const py = rect.y + rect.h / 2 + velocity.y * FLICK_PROJECTION_S;
+    let best = 'br';
+    let bestD = Infinity;
+    for (const spot of SPOTS) {
+        const r = spotRect(spot, rect, view, inset);
+        const d = Math.hypot(r.x + r.w / 2 - px, r.y + r.h / 2 - py);
+        if (d < bestD) {
+            bestD = d;
+            best = spot;
+        }
+    }
+    return { spot: best };
+}
+/** The spot a tucked HUD returns to: the nearer corner on its side. */
+export function untuck(place) {
+    if ('spot' in place)
+        return place.spot;
+    return `${place.y < 0.5 ? 't' : 'b'}${place.tuck === 'left' ? 'l' : 'r'}`;
+}
+/** The spot an arrow key moves to — the keyboard alternative to dragging. */
+export function neighbour(place, arrow) {
+    const spot = untuck(place);
+    if (!('spot' in place))
+        return { spot };
+    const cols = ['l', 'c', 'r'];
+    let row = rowOf(spot);
+    let ci = cols.indexOf(colOf(spot));
+    if (arrow === 'ArrowLeft')
+        ci = Math.max(0, ci - 1);
+    else if (arrow === 'ArrowRight')
+        ci = Math.min(2, ci + 1);
+    else if (arrow === 'ArrowUp')
+        row = 't';
+    else
+        row = 'b';
+    return { spot: `${row}${cols[ci]}` };
+}
+/** A stored place, validated; anything else is the default. */
+export function parsePlace(raw) {
+    if (typeof raw === 'string') {
+        try {
+            return parsePlace(JSON.parse(raw));
+        }
+        catch {
+            return DEFAULT_PLACE;
+        }
+    }
+    if (raw && typeof raw === 'object') {
+        const o = raw;
+        if (typeof o.spot === 'string' && SPOTS.includes(o.spot))
+            return { spot: o.spot };
+        if ((o.tuck === 'left' || o.tuck === 'right') && typeof o.y === 'number' && Number.isFinite(o.y))
+            return { tuck: o.tuck, y: clamp01(o.y) };
+    }
+    return DEFAULT_PLACE;
+}
+function clamp01(n) {
+    return Math.min(1, Math.max(0, n));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitrinka/link",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "vitrinka device link — the Netflix-style code flow that mints an ingest-only recorder token for the web and Expo recorders. Zero dependencies.",
   "license": "Elastic-2.0",
   "repository": {
@@ -17,6 +17,10 @@
       "types": "./build/index.d.ts",
       "default": "./build/index.js"
     },
+    "./dock": {
+      "types": "./build/dock.d.ts",
+      "default": "./build/dock.js"
+    },
     "./package.json": "./package.json"
   },
   "files": ["build", "README.md", "CHANGELOG.md"],