@vitrinka/link 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @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
+  `/w/<slug>` base; `startLink(base, { workspace })` appends
+  `workspace=<slug>` to `verifyUrl` and `qrUrl` so the approve page
+  preselects it (the start body stays `{kind, label}`), and
+  `pollLink(base, code, { workspace })` rejects a claim pinned to any other
+  workspace with `LinkWorkspaceMismatch` — its token is never returned. It
+  fails closed: a claim that names no workspace is refused too. A base
+  without `/w/<slug>` behaves as before.
+- `Linked` matches the claim the server sends: `expires_in` (seconds), not
+  the never-sent `expires_at`.
+
 ## 0.1.0
 
 - Initial release: `startLink`, `pollLink`, `linkOrigin`, `isUnauthorized`,

package/README.md

@@ -6,18 +6,40 @@ via a link, or another device via the server-rendered QR), and the recorder
 receives an ingest-only `vkr_` token. No baked secrets, no QR library.
 
 ```ts
-import { startLink, pollLink, LinkExpired } from '@vitrinka/link';
+import { startLink, pollLink, linkWorkspace, LinkExpired, LinkWorkspaceMismatch } from '@vitrinka/link';
 
-const start = await startLink('https://app.vitrinka.ai/w/acme', { label: 'Safari on macOS · app.example.test' });
+const base = 'https://app.vitrinka.ai/w/acme';
+const workspace = linkWorkspace(base); // 'acme' — undefined for a bare origin
+const start = await startLink(base, { label: 'Safari on macOS · app.example.test', workspace });
 start.user_code;  // 'ABCD-EFGH' — show it
-start.verifyUrl;  // open on the same device
+start.verifyUrl;  // open on the same device (…&workspace=acme preselects it)
 start.qrUrl;      // <img src> for the desktop→phone path (SVG from the server)
-const linked = await pollLink(start.base, start.device_code, { interval: start.interval });
+const linked = await pollLink(start.base, start.device_code, { interval: start.interval, workspace });
 linked.token;     // 'vkr_…' — store it, send it as the bearer
 ```
 
 Doors (at the base URL's origin): `POST /api/v1/cli/auth {kind:"recorder",label}` →
 201 `{device_code, user_code, verify_path, verify_url?, qr_path, interval,
 expires_in}`; `POST /api/v1/cli/auth/claim {device_code}` → 202 pending ·
-200 `{token, workspace, label, expires_at}` · 404 expired (`LinkExpired`).
+200 `{token, kind, workspace, label, expires_in}` · 404 expired (`LinkExpired`).
 A 401 from any session door means the token is dead: forget it and link again.
+
+A token only authenticates in the workspace it was approved into, so a
+`/w/<slug>` base passes that slug as `workspace`: it rides the approve and QR
+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/build/index.d.ts

@@ -7,7 +7,12 @@
  *   POST {origin}/api/v1/cli/auth        {kind:"recorder", label}
  *     → 201 {device_code, user_code, verify_path, verify_url?, qr_path, interval, expires_in}
  *   POST {origin}/api/v1/cli/auth/claim  {device_code}
- *     → 202 pending · 200 {token, workspace, label, expires_at} · 404 expired
+ *     → 202 pending · 200 {token, kind, workspace, label, expires_in} · 404 expired
+ *
+ * A base that addresses one workspace (`…/w/<slug>`) carries that slug as a
+ * `workspace=<slug>` hint on the approve and QR URLs (the approve page
+ * preselects it) and refuses a claim pinned to any other workspace — its
+ * token could never authenticate against `/w/<slug>`.
  *
  * Pure TypeScript: no DOM or React Native globals — `fetch` is taken from
  * the options or from globalThis.
@@ -29,14 +34,26 @@ export interface LinkStart {
 }
 export interface Linked {
     token: string;
+    /** Slug of the workspace the approver pinned the token to. */
     workspace: string;
     label: string;
-    expires_at: string;
+    /** Seconds until the (sliding) token expiry, as of the claim. */
+    expires_in: number;
 }
 /** The server no longer knows the code (expired or already consumed). */
 export declare class LinkExpired extends Error {
     constructor(message?: string);
 }
+/**
+ * The approver pinned the token to another workspace than the one the
+ * recorder records into. The token is discarded (never returned): every
+ * session door under `/w/<expected>` would answer it with a 401.
+ */
+export declare class LinkWorkspaceMismatch extends Error {
+    readonly linked: string;
+    readonly expected: string;
+    constructor(linked: string, expected: string);
+}
 export declare class LinkError extends Error {
     readonly status: number;
     constructor(message: string, status: number);
@@ -58,19 +75,35 @@ export interface LinkOptions {
 }
 /** The control-plane origin of a base URL. */
 export declare function linkOrigin(base: string): string;
+/**
+ * The workspace a base URL addresses — `<slug>` of a `/w/<slug>` path, split
+ * exactly like the server's tenant router — or undefined for a bare origin.
+ */
+export declare function linkWorkspace(base: string): string | undefined;
 /** A 401 from a session door: the stored token is dead. */
 export declare function isUnauthorized(status: number): boolean;
-/** Ask the server for a link code. */
+/**
+ * Ask the server for a link code. `workspace` (normally `linkWorkspace(base)`)
+ * rides the approve and QR URLs as a preselect hint only — the start body
+ * stays `{kind, label}`, because the server refuses unknown fields there.
+ */
 export declare function startLink(base: string, opts: {
     label: string;
+    workspace?: string;
 } & LinkOptions): Promise<LinkStart>;
 export interface PollOptions extends LinkOptions {
     /** Seconds between claims (min 2). */
     interval?: number;
+    /** The workspace the recorder records into; a claim pinned elsewhere rejects with LinkWorkspaceMismatch. */
+    workspace?: string;
     signal?: AbortSignal;
     /** Test seam: the sleep. */
     sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
 }
-/** Claim until approved. Resolves with the token; throws LinkExpired on 404, AbortError on abort. */
+/**
+ * Claim until approved. Resolves with the token; throws LinkExpired on 404,
+ * LinkWorkspaceMismatch when approved into another workspace than
+ * `opts.workspace`, AbortError on abort.
+ */
 export declare function pollLink(base: string, deviceCode: string, opts?: PollOptions): Promise<Linked>;
 export {};

package/build/index.js

@@ -7,7 +7,12 @@
  *   POST {origin}/api/v1/cli/auth        {kind:"recorder", label}
  *     → 201 {device_code, user_code, verify_path, verify_url?, qr_path, interval, expires_in}
  *   POST {origin}/api/v1/cli/auth/claim  {device_code}
- *     → 202 pending · 200 {token, workspace, label, expires_at} · 404 expired
+ *     → 202 pending · 200 {token, kind, workspace, label, expires_in} · 404 expired
+ *
+ * A base that addresses one workspace (`…/w/<slug>`) carries that slug as a
+ * `workspace=<slug>` hint on the approve and QR URLs (the approve page
+ * preselects it) and refuses a claim pinned to any other workspace — its
+ * token could never authenticate against `/w/<slug>`.
  *
  * Pure TypeScript: no DOM or React Native globals — `fetch` is taken from
  * the options or from globalThis.
@@ -19,6 +24,19 @@ export class LinkExpired extends Error {
         this.name = 'LinkExpired';
     }
 }
+/**
+ * The approver pinned the token to another workspace than the one the
+ * recorder records into. The token is discarded (never returned): every
+ * session door under `/w/<expected>` would answer it with a 401.
+ */
+export class LinkWorkspaceMismatch extends Error {
+    constructor(linked, expected) {
+        super(`linked into ${linked} — this app records into ${expected}; link again and pick ${expected}`);
+        this.linked = linked;
+        this.expected = expected;
+        this.name = 'LinkWorkspaceMismatch';
+    }
+}
 export class LinkError extends Error {
     constructor(message, status) {
         super(message);
@@ -46,6 +64,28 @@ export function permanentStatus(status) {
 export function linkOrigin(base) {
     return new URL(base).origin;
 }
+/**
+ * The workspace a base URL addresses — `<slug>` of a `/w/<slug>` path, split
+ * exactly like the server's tenant router — or undefined for a bare origin.
+ */
+export function linkWorkspace(base) {
+    const m = /^\/w\/([^/]+)/.exec(new URL(base).pathname);
+    if (!m?.[1])
+        return undefined;
+    try {
+        return decodeURIComponent(m[1]);
+    }
+    catch {
+        return m[1];
+    }
+}
+function withWorkspace(url, workspace) {
+    if (!workspace)
+        return url;
+    const u = new URL(url);
+    u.searchParams.set('workspace', workspace);
+    return u.href;
+}
 /** A 401 from a session door: the stored token is dead. */
 export function isUnauthorized(status) {
     return status === 401;
@@ -90,7 +130,11 @@ function requireString(w, key, status) {
         throw new LinkError(`link start → malformed payload (${key})`, status);
     return v;
 }
-/** Ask the server for a link code. */
+/**
+ * Ask the server for a link code. `workspace` (normally `linkWorkspace(base)`)
+ * rides the approve and QR URLs as a preselect hint only — the start body
+ * stays `{kind, label}`, because the server refuses unknown fields there.
+ */
 export async function startLink(base, opts) {
     const origin = linkOrigin(base);
     const res = await fetcher(opts)(`${origin}/api/v1/cli/auth`, {
@@ -122,8 +166,8 @@ export async function startLink(base, opts) {
         device_code: deviceCode,
         user_code: userCode,
         verify_path: verifyPath,
-        verifyUrl: sameOriginUrl(origin, typeof w.verify_url === 'string' ? w.verify_url : undefined, verifyPath, `/cli-auth?code=${encodeURIComponent(userCode)}`),
-        qrUrl: sameOriginUrl(origin, qrPath, qrPath, `/cli-auth/qr?code=${encodeURIComponent(userCode)}`),
+        verifyUrl: withWorkspace(sameOriginUrl(origin, typeof w.verify_url === 'string' ? w.verify_url : undefined, verifyPath, `/cli-auth?code=${encodeURIComponent(userCode)}`), opts.workspace),
+        qrUrl: withWorkspace(sameOriginUrl(origin, qrPath, qrPath, `/cli-auth/qr?code=${encodeURIComponent(userCode)}`), opts.workspace),
         interval: Math.max(2, Number(w.interval) || 2),
         expires_in: Number(w.expires_in) || 0,
     };
@@ -148,7 +192,11 @@ function abortError() {
     e.name = 'AbortError';
     return e;
 }
-/** Claim until approved. Resolves with the token; throws LinkExpired on 404, AbortError on abort. */
+/**
+ * Claim until approved. Resolves with the token; throws LinkExpired on 404,
+ * LinkWorkspaceMismatch when approved into another workspace than
+ * `opts.workspace`, AbortError on abort.
+ */
 export async function pollLink(base, deviceCode, opts = {}) {
     const origin = linkOrigin(base);
     const f = fetcher(opts);
@@ -165,8 +213,17 @@ export async function pollLink(base, deviceCode, opts = {}) {
             body: JSON.stringify({ device_code: deviceCode }),
             signal: opts.signal,
         });
-        if (res.status === 200)
-            return (await res.json());
+        if (res.status === 200) {
+            const linked = (await res.json());
+            // Fail closed: a recorder claim always names its workspace (the server
+            // sets it for kind recorder), so a missing or non-string one is refused
+            // like a foreign one — never stored against a base it cannot serve.
+            if (opts.workspace && linked.workspace !== opts.workspace) {
+                const got = typeof linked.workspace === 'string' && linked.workspace ? linked.workspace : '(no workspace)';
+                throw new LinkWorkspaceMismatch(got, opts.workspace);
+            }
+            return linked;
+        }
         if (res.status === 404 || res.status === 410)
             throw new LinkExpired();
         if (res.status !== 202)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitrinka/link",
-  "version": "0.1.0",
+  "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"],