nudge-ui 0.2.0 → 0.2.1

package/dist/transport/editor.d.ts

@@ -0,0 +1,28 @@
+/** 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;
+/** 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;
+/** Returns whether this browser tab should remain outside the editor. */
+export declare function hasNudgeUiDirectTabIntent(): boolean;
+export type NudgeUiClientEntry = {
+    readonly kind: "bootstrap";
+} | {
+    readonly kind: "direct";
+} | {
+    readonly kind: "redirect";
+    readonly href: string;
+};
+/** Chooses the browser-client role before any runtime manifest is fetched. */
+export declare function resolveNudgeUiClientEntry(href: string, editorDocument: boolean, canvasRenderer: boolean, directTab?: boolean): 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,132 @@
+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, isReservedNudgeUiRoute, } from "./routes.js";
+const TARGET_QUERY_PARAM = "url";
+const DIRECT_TAB_SESSION_KEY = "nudge-ui:direct-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);
+        return entry.get(NUDGE_UI_DIRECT_QUERY_PARAM) !== "1";
+    });
+    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;
+}
+/** Returns whether this application location explicitly bypasses editor entry. */
+export function isNudgeUiDirectUrl(href) {
+    const url = new URL(href);
+    return url.searchParams.get(NUDGE_UI_DIRECT_QUERY_PARAM) === "1";
+}
+/** Remembers that this browser tab was explicitly opened outside the editor. */
+export function rememberNudgeUiDirectTabIntent() {
+    try {
+        sessionStorage.setItem(DIRECT_TAB_SESSION_KEY, "1");
+    }
+    catch {
+        // Storage denial must not prevent a one-page direct application view.
+    }
+}
+/** Returns whether this browser tab should remain outside the editor. */
+export function hasNudgeUiDirectTabIntent() {
+    try {
+        return sessionStorage.getItem(DIRECT_TAB_SESSION_KEY) === "1";
+    }
+    catch {
+        return false;
+    }
+}
+/** Chooses the browser-client role before any runtime manifest is fetched. */
+export function resolveNudgeUiClientEntry(href, editorDocument, canvasRenderer, directTab = false) {
+    if (editorDocument || canvasRenderer)
+        return { kind: "bootstrap" };
+    if (isNudgeUiDirectUrl(href) || directTab)
+        return { kind: "direct" };
+    return { kind: "redirect", href: createNudgeUiEditorUrl(href) };
+}
+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,14 @@
 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";
+/** Query parameter that opens an application document without the editor. */
+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,16 @@
 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";
+/** Query parameter that opens an application document without the editor. */
+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.1",
   "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/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();
-}