nudge-ui 0.2.0 → 0.2.2

package/dist/transport/editor.d.ts

@@ -0,0 +1,47 @@
+/** Returns the editor URL for one same-origin application location. */
+export declare function createNudgeUiEditorUrl(applicationHref: string): string;
+/** Resolves the application URL carried by an editor URL. */
+export declare function readNudgeUiEditorTarget(editorHref: string): string | null;
+type RequestHeaderValue = string | readonly string[] | undefined;
+/** Returns whether a host request should receive the pure editor document. */
+export declare function isNudgeUiEditorDocumentRequest(requestHref: string, method: string | undefined, headers: Record<string, RequestHeaderValue> | undefined): boolean;
+/** Adds the persistent marker that bypasses editor entry for a plain app view. */
+export declare function createNudgeUiDirectUrl(applicationHref: string): string;
+/** Reads the public `nudge-ui=off` / `nudge-ui=on` switch from an application URL. */
+export declare function readNudgeUiQuerySwitch(href: string): "off" | "on" | null;
+/** Returns whether this application location explicitly bypasses editor entry. */
+export declare function isNudgeUiDirectUrl(href: string): boolean;
+/** Remembers that this browser tab was explicitly opened outside the editor. */
+export declare function rememberNudgeUiDirectTabIntent(): void;
+/** Remembers an explicit URL switch so later navigations in this tab keep it. */
+export declare function rememberNudgeUiTabSwitch(value: "off" | "on"): void;
+/** Returns whether this browser tab should remain outside the editor. */
+export declare function hasNudgeUiDirectTabIntent(): boolean;
+/** Returns whether this browser tab explicitly asked for the editor with `nudge-ui=on`. */
+export declare function hasNudgeUiForcedTabIntent(): boolean;
+export type NudgeUiClientEntry = {
+    readonly kind: "bootstrap";
+} | {
+    readonly kind: "direct";
+} | {
+    readonly kind: "redirect";
+    readonly href: string;
+}
+/** An automated browser that enters the editor only when the host opts in. */
+ | {
+    readonly kind: "automated";
+    readonly href: string;
+};
+export interface NudgeUiClientEntryContext {
+    readonly editorDocument: boolean;
+    readonly canvasRenderer: boolean;
+    readonly directTab?: boolean;
+    readonly forcedTab?: boolean;
+    /** `navigator.webdriver`: Playwright, Puppeteer, Selenium, and headless Chrome. */
+    readonly automated?: boolean;
+}
+/** Chooses the browser-client role before any runtime manifest is fetched. */
+export declare function resolveNudgeUiClientEntry(href: string, context: NudgeUiClientEntryContext): NudgeUiClientEntry;
+/** Renders the host-neutral editor document served by every development Adapter. */
+export declare function createNudgeUiEditorDocument(): string;
+export {};

package/dist/transport/editor.js

@@ -0,0 +1,163 @@
+import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_DIRECT_QUERY_PARAM, NUDGE_UI_EDITOR_QUERY_PARAM, NUDGE_UI_EDITOR_QUERY_VALUE, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_MOUNT_ID, NUDGE_UI_OFF_QUERY_VALUE, NUDGE_UI_ON_QUERY_VALUE, isReservedNudgeUiRoute, } from "./routes.js";
+const TARGET_QUERY_PARAM = "url";
+const DIRECT_TAB_SESSION_KEY = "nudge-ui:direct-tab";
+const FORCED_TAB_SESSION_KEY = "nudge-ui:forced-tab";
+/** Returns the editor URL for one same-origin application location. */
+export function createNudgeUiEditorUrl(applicationHref) {
+    const applicationUrl = new URL(applicationHref);
+    assertApplicationUrl(applicationUrl);
+    const retainedSegments = applicationUrl.search.slice(1).split("&").filter((segment) => {
+        const entry = new URLSearchParams(segment);
+        const value = entry.get(NUDGE_UI_EDITOR_QUERY_PARAM);
+        return entry.get(NUDGE_UI_DIRECT_QUERY_PARAM) !== "1"
+            && value !== NUDGE_UI_OFF_QUERY_VALUE
+            && value !== NUDGE_UI_ON_QUERY_VALUE;
+    });
+    applicationUrl.search = retainedSegments.join("&");
+    if (applicationUrl.searchParams.getAll(NUDGE_UI_EDITOR_QUERY_PARAM).includes(NUDGE_UI_EDITOR_QUERY_VALUE)) {
+        return applicationUrl.href;
+    }
+    const hash = applicationUrl.hash;
+    applicationUrl.hash = "";
+    applicationUrl.search = `${applicationUrl.search}${applicationUrl.search ? "&" : "?"}${NUDGE_UI_EDITOR_QUERY_PARAM}=${NUDGE_UI_EDITOR_QUERY_VALUE}`;
+    applicationUrl.hash = hash;
+    return applicationUrl.href;
+}
+/** Resolves the application URL carried by an editor URL. */
+export function readNudgeUiEditorTarget(editorHref) {
+    const editorUrl = new URL(editorHref);
+    if (editorUrl.pathname !== NUDGE_UI_EDITOR_PATH) {
+        if (!editorUrl.searchParams.getAll(NUDGE_UI_EDITOR_QUERY_PARAM).includes(NUDGE_UI_EDITOR_QUERY_VALUE)) {
+            return null;
+        }
+        const retainedSegments = editorUrl.search.slice(1).split("&").filter((segment) => {
+            const entry = new URLSearchParams(segment);
+            return entry.get(NUDGE_UI_EDITOR_QUERY_PARAM) !== NUDGE_UI_EDITOR_QUERY_VALUE;
+        });
+        editorUrl.search = retainedSegments.join("&");
+        return isApplicationUrl(editorUrl) ? editorUrl.href : null;
+    }
+    const target = editorUrl.searchParams.get(TARGET_QUERY_PARAM);
+    if (!target)
+        return null;
+    try {
+        const targetUrl = new URL(target, editorUrl.origin);
+        return targetUrl.origin === editorUrl.origin && isApplicationUrl(targetUrl)
+            ? targetUrl.href
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns whether a host request should receive the pure editor document. */
+export function isNudgeUiEditorDocumentRequest(requestHref, method, headers) {
+    const normalizedMethod = (method ?? "GET").toUpperCase();
+    if (normalizedMethod !== "GET" && normalizedMethod !== "HEAD")
+        return false;
+    const url = new URL(requestHref, "http://nudge-ui.local");
+    if (url.pathname === NUDGE_UI_EDITOR_PATH)
+        return true;
+    if (!isApplicationUrl(url))
+        return false;
+    if (!url.searchParams.getAll(NUDGE_UI_EDITOR_QUERY_PARAM).includes(NUDGE_UI_EDITOR_QUERY_VALUE))
+        return false;
+    const header = (name) => {
+        const value = headers?.[name] ?? headers?.[name.toLowerCase()];
+        return typeof value === "string" ? value : value?.join(",") ?? "";
+    };
+    return header("sec-fetch-dest").toLowerCase() === "document"
+        || header("accept").toLowerCase().includes("text/html");
+}
+/** Adds the persistent marker that bypasses editor entry for a plain app view. */
+export function createNudgeUiDirectUrl(applicationHref) {
+    const url = new URL(applicationHref);
+    assertApplicationUrl(url);
+    url.searchParams.set(NUDGE_UI_DIRECT_QUERY_PARAM, "1");
+    return url.href;
+}
+/** Reads the public `nudge-ui=off` / `nudge-ui=on` switch from an application URL. */
+export function readNudgeUiQuerySwitch(href) {
+    const url = new URL(href);
+    const values = url.searchParams.getAll(NUDGE_UI_EDITOR_QUERY_PARAM);
+    if (values.includes(NUDGE_UI_OFF_QUERY_VALUE) || url.searchParams.get(NUDGE_UI_DIRECT_QUERY_PARAM) === "1") {
+        return "off";
+    }
+    return values.includes(NUDGE_UI_ON_QUERY_VALUE) ? "on" : null;
+}
+/** Returns whether this application location explicitly bypasses editor entry. */
+export function isNudgeUiDirectUrl(href) {
+    return readNudgeUiQuerySwitch(href) === "off";
+}
+/** Remembers that this browser tab was explicitly opened outside the editor. */
+export function rememberNudgeUiDirectTabIntent() {
+    rememberNudgeUiTabSwitch("off");
+}
+/** Remembers an explicit URL switch so later navigations in this tab keep it. */
+export function rememberNudgeUiTabSwitch(value) {
+    try {
+        sessionStorage.setItem(value === "off" ? DIRECT_TAB_SESSION_KEY : FORCED_TAB_SESSION_KEY, "1");
+        sessionStorage.removeItem(value === "off" ? FORCED_TAB_SESSION_KEY : DIRECT_TAB_SESSION_KEY);
+    }
+    catch {
+        // Storage denial must not prevent the current page from honoring the switch.
+    }
+}
+/** Returns whether this browser tab should remain outside the editor. */
+export function hasNudgeUiDirectTabIntent() {
+    return readTabFlag(DIRECT_TAB_SESSION_KEY);
+}
+/** Returns whether this browser tab explicitly asked for the editor with `nudge-ui=on`. */
+export function hasNudgeUiForcedTabIntent() {
+    return readTabFlag(FORCED_TAB_SESSION_KEY);
+}
+function readTabFlag(key) {
+    try {
+        return sessionStorage.getItem(key) === "1";
+    }
+    catch {
+        return false;
+    }
+}
+/** Chooses the browser-client role before any runtime manifest is fetched. */
+export function resolveNudgeUiClientEntry(href, context) {
+    if (context.editorDocument || context.canvasRenderer)
+        return { kind: "bootstrap" };
+    const urlSwitch = readNudgeUiQuerySwitch(href);
+    if (urlSwitch === "off")
+        return { kind: "direct" };
+    const forced = urlSwitch === "on" || context.forcedTab === true;
+    if (!forced && context.directTab === true)
+        return { kind: "direct" };
+    const editorHref = createNudgeUiEditorUrl(href);
+    if (context.automated === true && !forced)
+        return { kind: "automated", href: editorHref };
+    return { kind: "redirect", href: editorHref };
+}
+function isApplicationUrl(url) {
+    return (url.protocol === "http:" || url.protocol === "https:")
+        && url.username === ""
+        && url.password === ""
+        && !isReservedNudgeUiRoute(url.pathname);
+}
+function assertApplicationUrl(url) {
+    if (!isApplicationUrl(url)) {
+        throw new TypeError("Nudge UI application URLs must be HTTP(S) URLs outside its reserved route namespace.");
+    }
+}
+/** Renders the host-neutral editor document served by every development Adapter. */
+export function createNudgeUiEditorDocument() {
+    return `<!doctype html>
+<html lang="en" data-nudge-ui-editor>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Nudge UI</title>
+  <style>html,body,#${NUDGE_UI_MOUNT_ID}{width:100%;height:100%;margin:0}body{overflow:hidden}</style>
+</head>
+<body>
+  <div id="${NUDGE_UI_MOUNT_ID}"></div>
+  <script type="module" src="${NUDGE_UI_CLIENT_PATH}" data-nudge-ui-client data-nudge-ui-manifest="${NUDGE_UI_MANIFEST_PATH}"></script>
+</body>
+</html>`;
+}

package/dist/transport/index.d.ts

@@ -4,5 +4,6 @@
  * Anything needing Node belongs in `project/`.
  */
 export * from "./routes.js";
+export * from "./editor.js";
 /** Envelope version understood by the browser client. */
 export declare const NUDGE_UI_MANIFEST_VERSION = 1;

package/dist/transport/index.js

@@ -4,5 +4,6 @@
  * Anything needing Node belongs in `project/`.
  */
 export * from "./routes.js";
+export * from "./editor.js";
 /** Envelope version understood by the browser client. */
 export const NUDGE_UI_MANIFEST_VERSION = 1;

package/dist/transport/routes.d.ts

@@ -7,7 +7,17 @@
 export declare const NUDGE_UI_ROUTE_PREFIX = "/__nudge_ui__/";
 export declare const NUDGE_UI_MANIFEST_PATH = "/__nudge_ui__/manifest";
 export declare const NUDGE_UI_CLIENT_PATH = "/__nudge_ui__/client.mjs";
+/** Pure controller document that hosts the editor chrome. */
+export declare const NUDGE_UI_EDITOR_PATH = "/__nudge_ui__/editor";
 /** Server-sent events announcing settled project changes. */
 export declare const NUDGE_UI_RELOAD_PATH = "/__nudge_ui__/reload";
 export declare const NUDGE_UI_MOUNT_ID = "nudge-ui-root";
+/** Query marker that presents an application route through the editor shell. */
+export declare const NUDGE_UI_EDITOR_QUERY_PARAM = "nudge-ui";
+export declare const NUDGE_UI_EDITOR_QUERY_VALUE = "editor";
+/** Public `nudge-ui` values that turn the inspector off or on for one browser tab. */
+export declare const NUDGE_UI_OFF_QUERY_VALUE = "off";
+export declare const NUDGE_UI_ON_QUERY_VALUE = "on";
+/** Internal alias of `nudge-ui=off` kept for existing direct-view links. */
+export declare const NUDGE_UI_DIRECT_QUERY_PARAM = "__nudge_ui_direct";
 export declare function isReservedNudgeUiRoute(pathname: string): boolean;

package/dist/transport/routes.js

@@ -7,9 +7,19 @@
 export const NUDGE_UI_ROUTE_PREFIX = "/__nudge_ui__/";
 export const NUDGE_UI_MANIFEST_PATH = `${NUDGE_UI_ROUTE_PREFIX}manifest`;
 export const NUDGE_UI_CLIENT_PATH = `${NUDGE_UI_ROUTE_PREFIX}client.mjs`;
+/** Pure controller document that hosts the editor chrome. */
+export const NUDGE_UI_EDITOR_PATH = `${NUDGE_UI_ROUTE_PREFIX}editor`;
 /** Server-sent events announcing settled project changes. */
 export const NUDGE_UI_RELOAD_PATH = `${NUDGE_UI_ROUTE_PREFIX}reload`;
 export const NUDGE_UI_MOUNT_ID = "nudge-ui-root";
+/** Query marker that presents an application route through the editor shell. */
+export const NUDGE_UI_EDITOR_QUERY_PARAM = "nudge-ui";
+export const NUDGE_UI_EDITOR_QUERY_VALUE = "editor";
+/** Public `nudge-ui` values that turn the inspector off or on for one browser tab. */
+export const NUDGE_UI_OFF_QUERY_VALUE = "off";
+export const NUDGE_UI_ON_QUERY_VALUE = "on";
+/** Internal alias of `nudge-ui=off` kept for existing direct-view links. */
+export const NUDGE_UI_DIRECT_QUERY_PARAM = "__nudge_ui_direct";
 export function isReservedNudgeUiRoute(pathname) {
     return pathname === NUDGE_UI_ROUTE_PREFIX.slice(0, -1)
         || pathname.startsWith(NUDGE_UI_ROUTE_PREFIX);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nudge-ui",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Development-only visual UI inspector. One package, one subpath per host.",
   "license": "MIT",
   "repository": {
@@ -79,7 +79,9 @@
     "@base-ui/react": "^1.7.0",
     "@tabler/icons-react": "^3.46.0",
     "magic-string": "^0.30.21",
+    "modern-screenshot": "^4.7.0",
     "parse5": "^7.3.0",
+    "perfect-freehand": "^1.2.3",
     "postcss": "^8.5.26",
     "typescript": "^5.9.3"
   },

package/dist/inspector/shell/DomNavigation.d.ts

@@ -1,8 +0,0 @@
-import type { ReactElement } from "react";
-import type { SelectedElement } from "../selection/selectionStore.js";
-interface DomNavigationProps {
-    selected: SelectedElement;
-    hierarchy: HTMLElement[];
-}
-export declare function DomNavigation({ selected, hierarchy }: DomNavigationProps): ReactElement | null;
-export {};

package/dist/inspector/shell/DomNavigation.js

@@ -1,30 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { resolveSelectionFromElement } from "../selection/resolveSelection.js";
-import { setSelectedElement } from "../selection/selectionStore.js";
-import { computeDescendants } from "../selection/hierarchy.js";
-import { Button } from "../ui/Button.js";
-const MAX_PARENT_LEVELS = 2;
-const MAX_CHILD_NODES = 2;
-function nodeLabel(node) {
-    return node.getAttribute("data-cid") ?? node.localName;
-}
-function nodeDescription(node) {
-    const id = node.id ? `#${node.id}` : "";
-    const className = typeof node.className === "string"
-        ? node.className.trim().split(/\s+/).filter(Boolean).slice(0, 2).map((name) => `.${name}`).join("")
-        : "";
-    const source = node.getAttribute("data-src");
-    return `${node.localName}${id}${className}${source ? ` — ${source}` : ""}`;
-}
-function selectNode(node) {
-    const resolved = resolveSelectionFromElement(node);
-    if (resolved)
-        setSelectedElement(resolved);
-}
-export function DomNavigation({ selected, hierarchy }) {
-    const parents = hierarchy.slice(1, MAX_PARENT_LEVELS + 1);
-    const children = computeDescendants(selected.domElement, 2, MAX_CHILD_NODES);
-    if (parents.length === 0 && children.length === 0)
-        return null;
-    return (_jsxs("section", { className: "dom-navigation", "data-test": "dom-navigation", "aria-label": "DOM navigation", children: [_jsx("div", { className: "dom-navigation__header", children: _jsx("span", { className: "dom-navigation__title", children: "DOM" }) }), parents.length > 0 ? (_jsxs("div", { className: "dom-navigation__group", "data-test": "dom-parents", children: [_jsx("span", { className: "dom-navigation__label", children: "Parents" }), _jsx("div", { className: "dom-navigation__items", children: parents.map((node, index) => (_jsxs(Button, { size: "compact", variant: "quiet", className: "dom-navigation__item", "data-test": "dom-parent-step", "data-depth": index + 1, "data-cid": node.getAttribute("data-cid") ?? undefined, title: nodeDescription(node), onClick: () => selectNode(node), children: [_jsx("span", { "aria-hidden": "true", children: "\u2191" }), index === 0 ? "Parent" : "Grandparent", _jsx("span", { className: "dom-navigation__value", children: nodeLabel(node) })] }, `${index}-${nodeLabel(node)}`))) })] })) : null, children.length > 0 ? (_jsxs("div", { className: "dom-navigation__group", "data-test": "dom-children", children: [_jsx("span", { className: "dom-navigation__label", children: "Children" }), _jsx("div", { className: "dom-navigation__items", children: children.map(({ element, depth }, index) => (_jsxs(Button, { size: "compact", variant: "quiet", className: "dom-navigation__item", "data-test": "dom-child-step", "data-depth": depth, "data-cid": element.getAttribute("data-cid") ?? undefined, title: nodeDescription(element), onClick: () => selectNode(element), children: [_jsx("span", { "aria-hidden": "true", children: "\u2193" }), depth === 1 ? "Child" : "Descendant", _jsx("span", { className: "dom-navigation__value", children: nodeLabel(element) })] }, `${depth}-${index}-${nodeLabel(element)}`))) })] })) : null] }));
-}

package/dist/inspector/shell/panelLayout.d.ts

@@ -1,2 +0,0 @@
-export declare function setInspectorLayoutOpen(open: boolean): void;
-export declare function clearInspectorLayout(): void;

package/dist/inspector/shell/panelLayout.js

@@ -1,29 +0,0 @@
-const LAYOUT_STYLE_ID = "nudge-ui-panel-layout";
-const PANEL_LAYOUT_ATTRIBUTE = "data-nudge-ui-panel";
-const LAYOUT_STYLES = `
-html[${PANEL_LAYOUT_ATTRIBUTE}="open"] body {
-  margin-right: min(320px, 100vw);
-  transition: margin-right 180ms ease;
-}
-`;
-function ensureLayoutStyles() {
-    if (document.getElementById(LAYOUT_STYLE_ID))
-        return;
-    const style = document.createElement("style");
-    style.id = LAYOUT_STYLE_ID;
-    style.textContent = LAYOUT_STYLES;
-    document.head.appendChild(style);
-}
-export function setInspectorLayoutOpen(open) {
-    const root = document.documentElement;
-    if (open) {
-        ensureLayoutStyles();
-        root.setAttribute(PANEL_LAYOUT_ATTRIBUTE, "open");
-        return;
-    }
-    root.removeAttribute(PANEL_LAYOUT_ATTRIBUTE);
-}
-export function clearInspectorLayout() {
-    document.documentElement.removeAttribute(PANEL_LAYOUT_ATTRIBUTE);
-    document.getElementById(LAYOUT_STYLE_ID)?.remove();
-}