@hyperframes/inspector 0.0.0-stage → 0.8.150

package/dist/types/inspector/src/engine.d.ts

@@ -0,0 +1,35 @@
+import type { TimelineRequest } from "../../core/src/runtime/timelineInspection.js";
+import { type ElementMap } from "./elementMap.js";
+import { mapInspection } from "./mapInspection.js";
+import { type PageRunner } from "./pageQueries.js";
+import type { Sources } from "./sources.js";
+import { type TimelineReport } from "./timelineReport.js";
+import type { InspectRequest, Snippet } from "./types.js";
+export interface SourceContext {
+    sources: Sources;
+    map: ReturnType<Sources["mapper"]>;
+}
+export interface InspectionView {
+    readonly generation: string;
+    readonly sourceVersion: string;
+    readonly pageGeneration?: string;
+    sourceContext(): SourceContext;
+    assertCurrent(): Promise<void>;
+}
+export type ComponentReport = ReturnType<typeof mapInspection>;
+export type ElementMapReport = ElementMap & {
+    sourceVersion: string;
+    generation: string;
+};
+export declare function inspectComponents(runner: PageRunner, view: InspectionView, request: InspectRequest, context: {
+    catalog: Map<string, Snippet>;
+    reused: boolean;
+    start: number;
+    visualState?: {
+        time: number | undefined;
+        duration: number | undefined;
+    };
+}): Promise<ComponentReport>;
+export declare function inspectTimeline(runner: PageRunner, view: InspectionView, request: TimelineRequest, reused: boolean): Promise<TimelineReport>;
+export declare function inspectElementMap(runner: PageRunner, view: InspectionView, file?: string): Promise<ElementMapReport>;
+export type { PageRunner, TimelineReport };

package/dist/types/inspector/src/live.d.ts

@@ -0,0 +1,18 @@
+import type { BundleScriptProvenance } from "../../core/src/compiler/htmlBundler.js";
+import type { TimelineRequest } from "../../core/src/runtime/timelineInspection.js";
+import { type ComponentReport, type ElementMapReport, type TimelineReport } from "./engine.js";
+import { type PageRunner } from "./pageQueries.js";
+import type { InspectRequest } from "./types.js";
+export interface LiveInspection {
+    readonly html: string;
+    readonly generation: string;
+    finalizeDocument(servedHtml: string): void;
+    inspect(runner: PageRunner, request: InspectRequest): Promise<ComponentReport>;
+    timeline(runner: PageRunner, request: TimelineRequest): Promise<TimelineReport>;
+    elementMap(runner: PageRunner): Promise<ElementMapReport>;
+}
+export declare function prepareLiveInspection(projectDir: string, html: string, provenance: readonly BundleScriptProvenance[], sourceVersion: string): LiveInspection;
+export declare function previewGeneration(runner: PageRunner): Promise<string | null>;
+export { fingerprint } from "./sources.js";
+export { componentsTool, timelineTool, toolContent, type InspectionTool } from "./tools.js";
+export type { ComponentReport, ElementMapReport, PageRunner, TimelineReport };

package/dist/types/inspector/src/mapInspection.d.ts

@@ -0,0 +1,76 @@
+import { Sources } from "./sources.js";
+import type { InspectRequest, RuntimeResponse, Snippet } from "./types.js";
+export declare function mapInspection(raw: RuntimeResponse, request: InspectRequest, context: {
+    sources: Sources;
+    map: ReturnType<Sources["mapper"]>;
+    catalog: Map<string, Snippet>;
+    generation: string;
+    sourceVersion: string;
+    reused: boolean;
+    start: number;
+    visualState?: {
+        time: number | undefined;
+        duration: number | undefined;
+    };
+}): {
+    generation: string;
+    visualState: {
+        time: number | undefined;
+        duration: number | undefined;
+    } | undefined;
+    sourceVersion: string;
+    reused: boolean;
+    results: {
+        target: number;
+        status: "missing" | "found" | "ambiguous" | "stale-ref" | "invalid-selector";
+        candidates: import("./types.js").ElementRef[];
+        candidatesOmitted: number;
+        animations: number;
+        coTargets: import("./types.js").ElementRef[];
+        unmappedAnimations: number;
+        scopeTruncated: boolean;
+    }[];
+    snippets: Snippet[];
+    omitted: {
+        id: string;
+        bytes: number;
+    }[];
+    omittedCount: number;
+    nextOffset: number | null;
+    coverage: string[];
+    recordLimitReached: boolean;
+    hooked: boolean;
+    debugAvailable: boolean;
+    elapsedMs: number;
+} | {
+    debug: RuntimeResponse;
+    generation: string;
+    visualState: {
+        time: number | undefined;
+        duration: number | undefined;
+    } | undefined;
+    sourceVersion: string;
+    reused: boolean;
+    results: {
+        target: number;
+        status: "missing" | "found" | "ambiguous" | "stale-ref" | "invalid-selector";
+        candidates: import("./types.js").ElementRef[];
+        candidatesOmitted: number;
+        animations: number;
+        coTargets: import("./types.js").ElementRef[];
+        unmappedAnimations: number;
+        scopeTruncated: boolean;
+    }[];
+    snippets: Snippet[];
+    omitted: {
+        id: string;
+        bytes: number;
+    }[];
+    omittedCount: number;
+    nextOffset: number | null;
+    coverage: string[];
+    recordLimitReached: boolean;
+    hooked: boolean;
+    debugAvailable: boolean;
+    elapsedMs: number;
+};

package/dist/types/inspector/src/outputSchemas.d.ts

@@ -0,0 +1,12 @@
+export declare const componentOutputSchema: {
+    type: string;
+    properties: Record<string, object>;
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare const timelineOutputSchema: {
+    type: string;
+    properties: Record<string, object>;
+    required: string[];
+    additionalProperties: boolean;
+};

package/dist/types/inspector/src/pageQueries.d.ts

@@ -0,0 +1,21 @@
+import type { TimelineEvent, TimelineRequest, TimelineRuntimeResult } from "../../core/src/runtime/timelineInspection.js";
+import type { RuntimeQuery, RuntimeResponse } from "./types.js";
+export interface PageRunner {
+    run<A, R>(fn: (arg: A) => R, arg: A): Promise<R>;
+}
+export interface PageTimeline extends TimelineRuntimeResult {
+    following: TimelineEvent[];
+    generation: string | null;
+}
+export interface PageRuntimeResponse extends RuntimeResponse {
+    generation: string | null;
+}
+export interface PlayerState {
+    time: number | undefined;
+    duration: number | undefined;
+}
+export declare function seekPage(time: number): void;
+export declare function playerStatePage(): PlayerState;
+export declare function queryPage(query: RuntimeQuery): PageRuntimeResponse;
+export declare function timelinePage(request: TimelineRequest): PageTimeline;
+export declare function liveGenerationPage(): string | null;

package/dist/types/inspector/src/pageServer.d.ts

@@ -0,0 +1,2 @@
+import type { Server } from "node:http";
+export declare function closeServer(server: Server): Promise<void>;

package/dist/types/inspector/src/requests.d.ts

@@ -0,0 +1,5 @@
+import type { TimelineRequest } from "../../core/src/runtime/timelineInspection.js";
+import type { InspectRequest } from "./types.js";
+export declare function validateInspectRequest(request: InspectRequest): void;
+export declare function validateTimelineRequest(request: TimelineRequest): void;
+export declare function assertGeneration(requested: string | undefined, current: string): void;

package/dist/types/inspector/src/service.d.ts

@@ -0,0 +1,98 @@
+import type { TimelineRequest } from "../../core/src/runtime/timelineInspection.js";
+import { type Page } from "puppeteer-core";
+import type { InspectRequest, Snippet } from "./types.js";
+export interface InspectorOptions {
+    executablePath?: string;
+    idleMs?: number;
+    instrument?: boolean;
+}
+export declare class Inspector {
+    readonly options: InspectorOptions;
+    private session?;
+    private browser?;
+    private tail;
+    private timer?;
+    private closed;
+    private catalog;
+    readonly project: string;
+    readonly stats: {
+        browserStarts: number;
+        pageLoads: number;
+        sourceLoads: number;
+        queries: number;
+        seeks: number;
+    };
+    constructor(project: string, options?: InspectorOptions);
+    private serialize;
+    private closeSession;
+    private ensure;
+    private view;
+    private idle;
+    inspect(request: InspectRequest): Promise<{
+        generation: string;
+        visualState: {
+            time: number | undefined;
+            duration: number | undefined;
+        } | undefined;
+        sourceVersion: string;
+        reused: boolean;
+        results: {
+            target: number;
+            status: "missing" | "found" | "ambiguous" | "stale-ref" | "invalid-selector";
+            candidates: import("./types.js").ElementRef[];
+            candidatesOmitted: number;
+            animations: number;
+            coTargets: import("./types.js").ElementRef[];
+            unmappedAnimations: number;
+            scopeTruncated: boolean;
+        }[];
+        snippets: Snippet[];
+        omitted: {
+            id: string;
+            bytes: number;
+        }[];
+        omittedCount: number;
+        nextOffset: number | null;
+        coverage: string[];
+        recordLimitReached: boolean;
+        hooked: boolean;
+        debugAvailable: boolean;
+        elapsedMs: number;
+    } | {
+        debug: import("./types.js").RuntimeResponse;
+        generation: string;
+        visualState: {
+            time: number | undefined;
+            duration: number | undefined;
+        } | undefined;
+        sourceVersion: string;
+        reused: boolean;
+        results: {
+            target: number;
+            status: "missing" | "found" | "ambiguous" | "stale-ref" | "invalid-selector";
+            candidates: import("./types.js").ElementRef[];
+            candidatesOmitted: number;
+            animations: number;
+            coTargets: import("./types.js").ElementRef[];
+            unmappedAnimations: number;
+            scopeTruncated: boolean;
+        }[];
+        snippets: Snippet[];
+        omitted: {
+            id: string;
+            bytes: number;
+        }[];
+        omittedCount: number;
+        nextOffset: number | null;
+        coverage: string[];
+        recordLimitReached: boolean;
+        hooked: boolean;
+        debugAvailable: boolean;
+        elapsedMs: number;
+    }>;
+    private query;
+    timeline(request: TimelineRequest): Promise<import("./timelineReport.js").TimelineReport>;
+    elementMap(): Promise<import("./engine.js").ElementMapReport>;
+    withPage<T>(fn: (page: Page) => Promise<T>): Promise<T>;
+    dispose(): Promise<void>;
+}

package/dist/types/inspector/src/sourceDependencies.d.ts

@@ -0,0 +1,5 @@
+export interface SourceRange {
+    start: number;
+    end: number;
+}
+export declare function sourceDependencies(text: string): (range: SourceRange) => SourceRange[];

package/dist/types/inspector/src/sources.d.ts

@@ -0,0 +1,49 @@
+import type { BundleScriptProvenance } from "../../core/src/compiler/htmlBundler.js";
+import type { ElementRef, Snippet } from "./types.js";
+import { type SourceRange } from "./sourceDependencies.js";
+interface Chunk {
+    file: string;
+    text: string;
+    offset: number;
+    dependencies: (range: SourceRange) => SourceRange[];
+    statements: {
+        start: number;
+        end: number;
+        type: string;
+    }[];
+}
+interface SourceFile {
+    text: string;
+    lines: number[];
+}
+export declare function fingerprint(project: string): string;
+export declare class Sources {
+    readonly project: string;
+    readonly files: Map<string, SourceFile>;
+    readonly chunks: Chunk[];
+    readonly cssRules: {
+        id: string;
+        selector: string;
+        file: string;
+        start: number;
+        end: number;
+    }[];
+    readonly htmlTags: {
+        file: string;
+        start: number;
+        end: number;
+        id?: string;
+        hfId?: string;
+        classes: string[];
+        tag: string;
+    }[];
+    constructor(project: string);
+    private addChunk;
+    private addCss;
+    slice(file: string, start: number, end: number, kind: string, target: number): Snippet | null;
+    markup(element: ElementRef, target: number): Snippet | null;
+    mapper(html: string, provenance: BundleScriptProvenance[]): (stack: string, target: number) => Snippet[];
+}
+export declare function markupSnippet(sources: Sources, element: ElementRef, target: number): Snippet | null;
+export declare function mergeSnippets(snippets: Snippet[], sources: Sources): Snippet[];
+export {};

package/dist/types/inspector/src/timelineReport.d.ts

@@ -0,0 +1,28 @@
+import type { TimelineEvent, TimelineRequest } from "../../core/src/runtime/timelineInspection.js";
+import type { PageTimeline } from "./pageQueries.js";
+import type { Sources } from "./sources.js";
+type SourceMap = ReturnType<Sources["mapper"]>;
+export interface TimelineReport {
+    text: string;
+    generation: string;
+    reused: boolean;
+    status: string;
+    candidates: PageTimeline["candidates"];
+    events: (Omit<TimelineEvent, "stack"> & {
+        stack: undefined;
+        sources: {
+            file: string;
+            line: number;
+        }[];
+    })[];
+    eventCount: number;
+    groupCount: number;
+    nextOffset: number | null;
+    warnings: string[];
+}
+export declare function formatTimeline(raw: PageTimeline, request: TimelineRequest, view: {
+    generation: string;
+    map: SourceMap;
+    reused: boolean;
+}): TimelineReport;
+export {};

package/dist/types/inspector/src/tools.d.ts

@@ -0,0 +1,18 @@
+export interface InspectionTool {
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    readonly outputSchema: Record<string, unknown>;
+}
+export declare const componentsTool: InspectionTool;
+export declare const timelineTool: InspectionTool;
+export declare function toolContent(tool: "components" | "timeline", report: object & {
+    text?: string;
+}): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: object & {
+        text?: string;
+    };
+};

package/dist/types/inspector/src/types.d.ts

@@ -0,0 +1 @@
+export type * from "../../core/src/runtime/inspectionTypes.js";

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@hyperframes/inspector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.8.150",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heygen-com/hyperframes",
+    "directory": "packages/inspector"
+  },
+  "files": [
+    "dist/service.js",
+    "dist/live.js",
+    "dist/inspection.js",
+    "dist/types",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types/inspector/src/service.d.ts",
+      "default": "./dist/service.js"
+    },
+    "./live": {
+      "types": "./dist/types/inspector/src/live.d.ts",
+      "default": "./dist/live.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@jridgewell/trace-mapping": "^0.3.29",
+    "acorn": "^8.17.0",
+    "esbuild": "^0.25.12",
+    "eslint-scope": "^9.1.2",
+    "postcss": "^8.5.8",
+    "puppeteer-core": "^25.8.0",
+    "@hyperframes/core": "0.8.151",
+    "@hyperframes/parsers": "0.8.151"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "serve": "bun run build && bun src/server.ts",
+    "mcp": "bun run build && bun src/mcp.ts",
+    "test:timeline": "bun tests/timeline.ts",
+    "test:timeline-compositions": "bun tests/timelineCompositions.ts",
+    "test:live": "bun run build && bun tests/live.ts",
+    "test:source-release": "bun tests/sourceRelease.ts",
+    "serve:node": "node dist/server.js"
+  }
 }