@redstone-md/mapr 0.0.2-alpha → 0.0.4-alpha

package/README.md

@@ -1,5 +1,7 @@
 # Mapr
 
+![Mapr banner](./assets/banner.svg)
+
 Mapr is a Bun-native CLI/TUI for reverse-engineering frontend websites and build outputs. It crawls a target site, collects analyzable frontend artifacts, runs a multi-agent AI analysis pipeline over chunked code, and writes a Markdown report with entry points, initialization flow, inferred call graph edges, restored names, artifact summaries, and investigation tips.
 
 This repository is public for source visibility and collaboration. The license remains source-available and restricted. Read the contribution and license sections before reusing or contributing to the codebase.
@@ -14,6 +16,7 @@ This repository is public for source visibility and collaboration. The license r
 - Same-origin crawler with bounded page count and crawl depth
 - JS bundle, worker, service worker, WASM, and source-map discovery
 - Iframe-aware crawling for same-origin embedded pages
+- Streaming AI generation with live throughput updates in the TUI
 - Local RAG mode for multi-megabyte bundles
 - Partial-report persistence when analysis fails mid-run
 - Headless automation mode for CI or batch workflows
@@ -39,7 +42,7 @@ Mapr does not analyze images, fonts, audio, video, PDFs, archives, or other pres
 - Built-in OpenAI-compatible presets for BlackBox AI, Nvidia NIM, and OnlySQ
 - Automatic model context-size detection from provider model metadata when available
 - Headless CLI mode for automation
-- Live crawler and swarm progress with agent-level tracking and progress bars
+- Live crawler and swarm progress with agent-level tracking, progress bars, and streaming TPS estimates
 
 ## Install
 
@@ -64,7 +67,7 @@ npx @redstone-md/mapr --help
 4. Crawl the target website, same-origin iframe pages, and discovered code artifacts with bounded page count and crawl depth
 5. Format analyzable content where possible
 6. Optionally build a local lexical RAG index for oversized artifacts
-7. Run a communicating swarm of analysis agents over chunked artifact content with structured-output fallback for providers that only support plain text
+7. Run a communicating swarm of analysis agents over chunked artifact content through streaming JSON generation so long-running requests keep producing output
 8. Generate a Markdown report in the current working directory
 
 ## Provider Presets
@@ -121,7 +124,7 @@ Mapr uses a communicating agent swarm per chunk:
 - `security`: identifies risks, persistence, caching, and operator tips
 - `synthesizer`: merges the upstream notes into the final chunk analysis
 
-Progress is shown directly in the TUI for crawler fetches, depth skips, discovered nested artifacts, and swarm agent/chunk execution.
+Progress is shown directly in the TUI for crawler fetches, depth skips, discovered nested artifacts, swarm agent/chunk execution, and live token-per-second estimates during provider streaming.
 
 ## Large Bundle Handling
 

package/assets/banner.svg

@@ -0,0 +1,50 @@
+<svg width="1280" height="320" viewBox="0 0 1280 320" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">Mapr repository banner</title>
+  <desc id="desc">A dark technical banner showing Mapr's flow from crawl to artifacts to report.</desc>
+  <rect width="1280" height="320" fill="#111315"/>
+  <rect x="24" y="24" width="1232" height="272" rx="14" fill="#15181B" stroke="#2A2E33"/>
+  <rect x="56" y="56" width="360" height="208" rx="12" fill="#181C20" stroke="#2E3339"/>
+  <rect x="460" y="56" width="360" height="208" rx="12" fill="#181C20" stroke="#2E3339"/>
+  <rect x="864" y="56" width="360" height="208" rx="12" fill="#181C20" stroke="#2E3339"/>
+
+  <text x="80" y="88" fill="#EEE6DA" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="28" font-weight="700">mapr</text>
+  <text x="80" y="114" fill="#8E877C" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">frontend reverse engineering for bun</text>
+
+  <text x="80" y="154" fill="#C67A3B" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13">crawl</text>
+  <text x="484" y="88" fill="#C67A3B" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13">artifacts</text>
+  <text x="888" y="88" fill="#C67A3B" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13">report</text>
+
+  <rect x="80" y="172" width="170" height="20" rx="6" fill="#22272C"/>
+  <rect x="80" y="204" width="240" height="20" rx="6" fill="#22272C"/>
+  <rect x="80" y="236" width="120" height="12" rx="6" fill="#7F6B52"/>
+  <rect x="210" y="236" width="112" height="12" rx="6" fill="#22272C"/>
+  <rect x="332" y="236" width="42" height="12" rx="6" fill="#22272C"/>
+
+  <rect x="500" y="114" width="88" height="36" rx="8" fill="#1F2428" stroke="#343A41"/>
+  <rect x="596" y="114" width="88" height="36" rx="8" fill="#1F2428" stroke="#343A41"/>
+  <rect x="692" y="114" width="88" height="36" rx="8" fill="#1F2428" stroke="#343A41"/>
+  <rect x="500" y="164" width="88" height="36" rx="8" fill="#1F2428" stroke="#343A41"/>
+  <rect x="596" y="164" width="88" height="36" rx="8" fill="#1F2428" stroke="#343A41"/>
+  <rect x="692" y="164" width="88" height="36" rx="8" fill="#1F2428" stroke="#343A41"/>
+  <text x="530" y="136" fill="#EEE6DA" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">js</text>
+  <text x="618" y="136" fill="#EEE6DA" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">sw</text>
+  <text x="705" y="136" fill="#EEE6DA" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">map</text>
+  <text x="522" y="186" fill="#EEE6DA" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">wasm</text>
+  <text x="607" y="186" fill="#EEE6DA" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">worker</text>
+  <text x="713" y="186" fill="#EEE6DA" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">rag</text>
+
+  <rect x="888" y="112" width="312" height="120" rx="10" fill="#1D2226" stroke="#343941"/>
+  <rect x="914" y="134" width="84" height="8" rx="4" fill="#C67A3B"/>
+  <rect x="914" y="156" width="182" height="8" rx="4" fill="#444B52"/>
+  <rect x="914" y="176" width="212" height="8" rx="4" fill="#444B52"/>
+  <rect x="914" y="196" width="168" height="8" rx="4" fill="#444B52"/>
+  <rect x="1108" y="156" width="66" height="52" rx="8" fill="#171B1E" stroke="#343941"/>
+  <path d="M1132 171H1150M1132 183H1148M1132 195H1144" stroke="#EEE6DA" stroke-width="2" stroke-linecap="round"/>
+
+  <path d="M392 160C414 160 426 160 446 160" stroke="#7F6B52" stroke-width="2.5" stroke-linecap="round"/>
+  <path d="M796 160C816 160 828 160 848 160" stroke="#7F6B52" stroke-width="2.5" stroke-linecap="round"/>
+  <path d="M438 160L426 154V166L438 160Z" fill="#C67A3B"/>
+  <path d="M840 160L828 154V166L840 160Z" fill="#C67A3B"/>
+
+  <text x="930" y="254" fill="#8E877C" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="12">crawl -> analyze -> report</text>
+</svg>

package/lib/ai-analyzer.ts

@@ -13,7 +13,7 @@ import {
   type ChunkAnalysis,
   PartialAnalysisError,
 } from "./analysis-schema";
-import { generateObjectWithTextFallback } from "./ai-json";
+import { generateObjectFromStream, type StreamedObjectTelemetry } from "./ai-json";
 import { artifactTypeSchema } from "./artifacts";
 import type { FormattedArtifact } from "./formatter";
 import { LocalArtifactRag } from "./local-rag";
@@ -38,7 +38,7 @@ const analyzeInputSchema = z.object({
   ),
 });
 export type AnalysisProgressStage = "artifact" | "chunk" | "agent";
-export type AnalysisProgressState = "started" | "completed";
+export type AnalysisProgressState = "started" | "streaming" | "completed";
 
 export interface AnalysisProgressEvent {
   stage: AnalysisProgressStage;
@@ -50,6 +50,9 @@ export interface AnalysisProgressEvent {
   chunkIndex?: number;
   chunkCount?: number;
   agent?: SwarmAgentName;
+  estimatedOutputTokens?: number;
+  outputTokens?: number;
+  tokensPerSecond?: number;
 }
 
 interface AnalyzerOptions {
@@ -153,6 +156,13 @@ function normalizeAiError(error: unknown): Error {
   return error;
 }
 
+function formatAgentTelemetrySuffix(telemetry: StreamedObjectTelemetry): string {
+  const tokenCount = telemetry.outputTokens ?? telemetry.estimatedOutputTokens;
+  const tokenLabel = telemetry.outputTokens !== undefined ? `${tokenCount} tok` : `~${tokenCount} tok`;
+  const tpsLabel = telemetry.tokensPerSecond !== undefined ? ` ${telemetry.tokensPerSecond} tps` : "";
+  return ` [${tokenLabel}${tpsLabel}]`;
+}
+
 export class AiBundleAnalyzer {
   private readonly providerClient: AiProviderClient;
   private readonly chunkSizeBytes: number;
@@ -302,23 +312,39 @@ export class AiBundleAnalyzer {
 
       if (agent === "synthesizer") {
         const synthesized = await this.runSynthesisAgent(input, memory, this.getRetrievedContext(agent, input, memory));
-        memory[agent] = synthesized;
+        memory[agent] = synthesized.object;
+        this.emitProgress({
+          stage: "agent",
+          state: "completed",
+          message: `${agent} agent completed ${input.artifact.url} chunk ${input.chunkIndex + 1}/${input.totalChunks}${formatAgentTelemetrySuffix(synthesized.telemetry)}`,
+          artifactIndex: input.artifactIndex,
+          artifactCount: input.artifactCount,
+          artifactUrl: input.artifact.url,
+          chunkIndex: input.chunkIndex + 1,
+          chunkCount: input.totalChunks,
+          agent,
+          estimatedOutputTokens: synthesized.telemetry.estimatedOutputTokens,
+          ...(synthesized.telemetry.outputTokens !== undefined ? { outputTokens: synthesized.telemetry.outputTokens } : {}),
+          ...(synthesized.telemetry.tokensPerSecond !== undefined ? { tokensPerSecond: synthesized.telemetry.tokensPerSecond } : {}),
+        });
       } else {
         const memo = await this.runMemoAgent(agent, input, memory, this.getRetrievedContext(agent, input, memory));
-        memory[agent] = memo;
+        memory[agent] = memo.object;
+        this.emitProgress({
+          stage: "agent",
+          state: "completed",
+          message: `${agent} agent completed ${input.artifact.url} chunk ${input.chunkIndex + 1}/${input.totalChunks}${formatAgentTelemetrySuffix(memo.telemetry)}`,
+          artifactIndex: input.artifactIndex,
+          artifactCount: input.artifactCount,
+          artifactUrl: input.artifact.url,
+          chunkIndex: input.chunkIndex + 1,
+          chunkCount: input.totalChunks,
+          agent,
+          estimatedOutputTokens: memo.telemetry.estimatedOutputTokens,
+          ...(memo.telemetry.outputTokens !== undefined ? { outputTokens: memo.telemetry.outputTokens } : {}),
+          ...(memo.telemetry.tokensPerSecond !== undefined ? { tokensPerSecond: memo.telemetry.tokensPerSecond } : {}),
+        });
       }
-
-      this.emitProgress({
-        stage: "agent",
-        state: "completed",
-        message: `${agent} agent completed ${input.artifact.url} chunk ${input.chunkIndex + 1}/${input.totalChunks}`,
-        artifactIndex: input.artifactIndex,
-        artifactCount: input.artifactCount,
-        artifactUrl: input.artifact.url,
-        chunkIndex: input.chunkIndex + 1,
-        chunkCount: input.totalChunks,
-        agent,
-      });
     }
 
     return chunkAnalysisSchema.parse(memory.synthesizer);
@@ -332,11 +358,13 @@ export class AiBundleAnalyzer {
       chunk: string;
       chunkIndex: number;
       totalChunks: number;
+      artifactIndex: number;
+      artifactCount: number;
     },
     memory: Partial<Record<SwarmAgentName, unknown>>,
     retrievedContext: string[],
-  ): Promise<AgentMemo> {
-    return generateObjectWithTextFallback({
+  ): Promise<{ object: AgentMemo; telemetry: StreamedObjectTelemetry }> {
+    return generateObjectFromStream({
       model: this.providerClient.getModel(),
       system: getSwarmAgentPrompt(agent),
       prompt: createPromptEnvelope({
@@ -359,6 +387,22 @@ export class AiBundleAnalyzer {
           store: false,
         },
       },
+      onProgress: (telemetry) => {
+        this.emitProgress({
+          stage: "agent",
+          state: "streaming",
+          message: `${agent} agent streaming ${input.artifact.url} chunk ${input.chunkIndex + 1}/${input.totalChunks}${formatAgentTelemetrySuffix(telemetry)}`,
+          artifactIndex: input.artifactIndex,
+          artifactCount: input.artifactCount,
+          artifactUrl: input.artifact.url,
+          chunkIndex: input.chunkIndex + 1,
+          chunkCount: input.totalChunks,
+          agent,
+          estimatedOutputTokens: telemetry.estimatedOutputTokens,
+          ...(telemetry.outputTokens !== undefined ? { outputTokens: telemetry.outputTokens } : {}),
+          ...(telemetry.tokensPerSecond !== undefined ? { tokensPerSecond: telemetry.tokensPerSecond } : {}),
+        });
+      },
     });
   }
 
@@ -369,11 +413,13 @@ export class AiBundleAnalyzer {
       chunk: string;
       chunkIndex: number;
       totalChunks: number;
+      artifactIndex: number;
+      artifactCount: number;
     },
     memory: Partial<Record<SwarmAgentName, unknown>>,
     retrievedContext: string[],
-  ): Promise<ChunkAnalysis> {
-    return generateObjectWithTextFallback({
+  ): Promise<{ object: ChunkAnalysis; telemetry: StreamedObjectTelemetry }> {
+    return generateObjectFromStream({
       model: this.providerClient.getModel(),
       system: getSwarmAgentPrompt("synthesizer"),
       prompt: createPromptEnvelope({
@@ -396,6 +442,22 @@ export class AiBundleAnalyzer {
           store: false,
         },
       },
+      onProgress: (telemetry) => {
+        this.emitProgress({
+          stage: "agent",
+          state: "streaming",
+          message: `synthesizer agent streaming ${input.artifact.url} chunk ${input.chunkIndex + 1}/${input.totalChunks}${formatAgentTelemetrySuffix(telemetry)}`,
+          artifactIndex: input.artifactIndex,
+          artifactCount: input.artifactCount,
+          artifactUrl: input.artifact.url,
+          chunkIndex: input.chunkIndex + 1,
+          chunkCount: input.totalChunks,
+          agent: "synthesizer",
+          estimatedOutputTokens: telemetry.estimatedOutputTokens,
+          ...(telemetry.outputTokens !== undefined ? { outputTokens: telemetry.outputTokens } : {}),
+          ...(telemetry.tokensPerSecond !== undefined ? { tokensPerSecond: telemetry.tokensPerSecond } : {}),
+        });
+      },
     });
   }
 
@@ -405,7 +467,7 @@ export class AiBundleAnalyzer {
     chunkAnalyses: ChunkAnalysis[],
   ): Promise<BundleAnalysis> {
     try {
-      const result = await generateObjectWithTextFallback({
+      const result = await generateObjectFromStream({
         model: this.providerClient.getModel(),
         system: [
           getGlobalMissionPrompt(),
@@ -436,7 +498,7 @@ export class AiBundleAnalyzer {
       });
 
       return finalAnalysisSchema.parse({
-        ...result,
+        ...result.object,
         artifactSummaries,
         analyzedChunkCount: chunkAnalyses.length,
       });

package/lib/ai-json.ts

@@ -1,7 +1,21 @@
-import { generateText, Output } from "ai";
+import { streamText } from "ai";
 import { z } from "zod";
 
 const jsonFencePattern = /^```(?:json)?\s*([\s\S]*?)\s*```$/i;
+const STREAM_PROGRESS_INTERVAL_MS = 750;
+const ESTIMATED_CHARS_PER_TOKEN = 4;
+
+export interface StreamedObjectTelemetry {
+  elapsedMs: number;
+  estimatedOutputTokens: number;
+  outputTokens?: number;
+  tokensPerSecond?: number;
+}
+
+export interface StreamedObjectResult<TOutput> {
+  object: TOutput;
+  telemetry: StreamedObjectTelemetry;
+}
 
 function extractBalancedJsonSlice(source: string): string | null {
   const startIndex = source.search(/[\[{]/);
@@ -15,7 +29,6 @@ function extractBalancedJsonSlice(source: string): string | null {
 
   for (let index = startIndex; index < source.length; index += 1) {
     const character = source[index];
-
     if (!character) {
       continue;
     }
@@ -53,6 +66,33 @@ function extractBalancedJsonSlice(source: string): string | null {
   return null;
 }
 
+function formatJsonSystemPrompt(system: string, contract: string): string {
+  return [
+    system,
+    "Return only one valid JSON object.",
+    "Do not wrap the JSON in markdown fences.",
+    "Do not add explanations before or after the JSON.",
+    contract,
+  ].join("\n");
+}
+
+function calculateTokensPerSecond(tokenCount: number, elapsedMs: number): number | undefined {
+  if (tokenCount <= 0 || elapsedMs < 250) {
+    return undefined;
+  }
+
+  return Number((tokenCount / (elapsedMs / 1000)).toFixed(1));
+}
+
+export function estimateTokenCountFromText(source: string): number {
+  const trimmed = source.trim();
+  if (trimmed.length === 0) {
+    return 0;
+  }
+
+  return Math.max(1, Math.ceil(trimmed.length / ESTIMATED_CHARS_PER_TOKEN));
+}
+
 export function extractJsonFromText(source: string): unknown {
   const trimmed = source.trim();
   if (!trimmed) {
@@ -74,22 +114,7 @@ export function extractJsonFromText(source: string): unknown {
   }
 }
 
-export function shouldFallbackToTextJson(error: unknown): boolean {
-  if (!(error instanceof Error)) {
-    return false;
-  }
-
-  const message = error.message.toLowerCase();
-  return (
-    message.includes("responseformat") ||
-    message.includes("structured output") ||
-    message.includes("structuredoutputs") ||
-    message.includes("response did not match schema") ||
-    message.includes("no object generated")
-  );
-}
-
-export async function generateObjectWithTextFallback<TOutput>(input: {
+export async function generateObjectFromStream<TOutput>(input: {
   model: unknown;
   system: string;
   prompt: string;
@@ -97,38 +122,57 @@ export async function generateObjectWithTextFallback<TOutput>(input: {
   contract: string;
   maxRetries?: number;
   providerOptions?: Record<string, unknown>;
-}): Promise<TOutput> {
-  try {
-    const structuredResult = await generateText({
-      model: input.model as never,
-      system: input.system,
-      prompt: input.prompt,
-      output: Output.object({ schema: input.schema }),
-      maxRetries: input.maxRetries ?? 2,
-      ...(input.providerOptions !== undefined ? { providerOptions: input.providerOptions as never } : {}),
-    });
-
-    return input.schema.parse(structuredResult.output);
-  } catch (error) {
-    if (!shouldFallbackToTextJson(error)) {
-      throw error;
-    }
-  }
+  onProgress?: (telemetry: StreamedObjectTelemetry) => void;
+}): Promise<StreamedObjectResult<TOutput>> {
+  let streamedText = "";
+  const startedAt = Date.now();
+  let lastProgressAt = 0;
 
-  const textResult = await generateText({
+  const result = streamText({
     model: input.model as never,
-    system: [
-      input.system,
-      "Return only one valid JSON object.",
-      "Do not wrap the JSON in markdown fences.",
-      "Do not add explanations before or after the JSON.",
-      input.contract,
-    ].join("\n"),
+    system: formatJsonSystemPrompt(input.system, input.contract),
     prompt: input.prompt,
-    output: Output.text(),
     maxRetries: input.maxRetries ?? 2,
     ...(input.providerOptions !== undefined ? { providerOptions: input.providerOptions as never } : {}),
   });
 
-  return input.schema.parse(extractJsonFromText(textResult.output));
+  for await (const textPart of result.textStream) {
+    streamedText += textPart;
+
+    const now = Date.now();
+    if (input.onProgress !== undefined && now - lastProgressAt >= STREAM_PROGRESS_INTERVAL_MS) {
+      const estimatedOutputTokens = estimateTokenCountFromText(streamedText);
+      const tokensPerSecond = calculateTokensPerSecond(estimatedOutputTokens, now - startedAt);
+      input.onProgress({
+        elapsedMs: now - startedAt,
+        estimatedOutputTokens,
+        ...(tokensPerSecond !== undefined ? { tokensPerSecond } : {}),
+      });
+      lastProgressAt = now;
+    }
+  }
+
+  let usage: Awaited<typeof result.usage> | undefined;
+  try {
+    usage = await result.usage;
+  } catch {
+    usage = undefined;
+  }
+  const elapsedMs = Date.now() - startedAt;
+  const estimatedOutputTokens = estimateTokenCountFromText(streamedText);
+  const outputTokens = usage?.outputTokens ?? undefined;
+  const tokensPerSecond = calculateTokensPerSecond(outputTokens ?? estimatedOutputTokens, elapsedMs);
+  const telemetry: StreamedObjectTelemetry = {
+    elapsedMs,
+    estimatedOutputTokens,
+    ...(outputTokens !== undefined ? { outputTokens } : {}),
+    ...(tokensPerSecond !== undefined ? { tokensPerSecond } : {}),
+  };
+
+  input.onProgress?.(telemetry);
+
+  return {
+    object: input.schema.parse(extractJsonFromText(streamedText)),
+    telemetry,
+  };
 }

package/lib/scraper.ts

@@ -37,6 +37,7 @@ export interface ScrapeResult {
 type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 type NumericScraperOptions = z.input<typeof scraperOptionsSchema>;
 type QueueEntry = { candidate: ArtifactCandidate; depth: number };
+type CrawlScope = "site" | "page";
 
 export interface ScraperProgressEvent {
   message: string;
@@ -53,6 +54,11 @@ function isPageCandidate(candidate: ArtifactCandidate, rootOrigin: string): bool
   return candidate.type === "html" && new URL(candidate.url).origin === rootOrigin;
 }
 
+function isRootLikeEntry(url: string): boolean {
+  const pathname = new URL(url).pathname.toLowerCase();
+  return pathname === "/" || pathname === "" || pathname.endsWith("/index.html") || pathname.endsWith("/index.htm");
+}
+
 function shouldFollowCandidate(candidate: ArtifactCandidate, rootOrigin: string): boolean {
   if (candidate.type === "html") {
     return new URL(candidate.url).origin === rootOrigin;
@@ -150,6 +156,7 @@ export class BundleScraper {
   public async scrape(pageUrl: string): Promise<ScrapeResult> {
     const validatedPageUrl = httpUrlSchema.parse(pageUrl);
     const rootOrigin = new URL(validatedPageUrl).origin;
+    const crawlScope: CrawlScope = isRootLikeEntry(validatedPageUrl) ? "site" : "page";
     const visitedUrls = new Set<string>();
     const htmlPages = new Set<string>();
     const artifacts: DiscoveredArtifact[] = [];
@@ -164,7 +171,9 @@ export class BundleScraper {
       },
     ];
 
-    queue.push(...(await this.discoverSupplementalPages(rootOrigin)).map((candidate) => ({ candidate, depth: 1 })));
+    if (crawlScope === "site") {
+      queue.push(...(await this.discoverSupplementalPages(rootOrigin)).map((candidate) => ({ candidate, depth: 1 })));
+    }
 
     while (queue.length > 0) {
       if (artifacts.length >= this.options.maxArtifacts) {
@@ -204,7 +213,7 @@ export class BundleScraper {
         depth,
       });
 
-      const artifact = await this.fetchArtifact(candidate, depth);
+      const artifact = await this.fetchArtifact(candidate, depth, candidate.url === validatedPageUrl);
       if (!artifact) {
         continue;
       }
@@ -217,7 +226,7 @@ export class BundleScraper {
         artifacts.push(artifact);
       }
 
-      const nestedCandidates = extractNestedCandidates(artifact);
+      const nestedCandidates = this.filterNestedCandidates(extractNestedCandidates(artifact), validatedPageUrl, crawlScope);
       for (const nestedCandidate of nestedCandidates) {
         if (!visitedUrls.has(nestedCandidate.url)) {
           queue.push({ candidate: nestedCandidate, depth: depth + 1 });
@@ -279,8 +288,12 @@ export class BundleScraper {
     return [...candidates.values()];
   }
 
-  private async fetchArtifact(candidate: ArtifactCandidate, depth: number): Promise<DiscoveredArtifact | null> {
-    const response = await this.fetchResponse(candidate.url, candidate.type);
+  private async fetchArtifact(candidate: ArtifactCandidate, depth: number, required: boolean): Promise<DiscoveredArtifact | null> {
+    const response = await this.fetchResponse(candidate.url, candidate.type, depth, required);
+    if (!response) {
+      return null;
+    }
+
     const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
 
     if (isIgnoredContentType(contentType)) {
@@ -335,7 +348,12 @@ export class BundleScraper {
     });
   }
 
-  private async fetchResponse(url: string, artifactType: ArtifactCandidate["type"]): Promise<Response> {
+  private async fetchResponse(
+    url: string,
+    artifactType: ArtifactCandidate["type"],
+    depth: number,
+    required: boolean,
+  ): Promise<Response | null> {
     try {
       const response = await this.fetcher(url, {
         headers: {
@@ -344,11 +362,31 @@ export class BundleScraper {
       });
 
       if (!response.ok) {
-        throw new Error(`Failed to fetch ${artifactType} from ${url}: ${response.status} ${response.statusText}`);
+        if (required) {
+          throw new Error(`Failed to fetch ${artifactType} from ${url}: ${response.status} ${response.statusText}`);
+        }
+
+        this.emitProgress({
+          message: `Skipping ${artifactType} after ${response.status} ${response.statusText}: ${url}`,
+          url,
+          type: artifactType,
+          depth,
+        });
+        return null;
       }
 
       return response;
     } catch (error) {
+      if (!required) {
+        this.emitProgress({
+          message: `Skipping ${artifactType} after fetch error: ${url}`,
+          url,
+          type: artifactType,
+          depth,
+        });
+        return null;
+      }
+
       if (error instanceof Error) {
         throw new Error(`Unable to fetch ${artifactType} artifact ${url}: ${error.message}`);
       }
@@ -378,6 +416,50 @@ export class BundleScraper {
   private emitProgress(event: ScraperProgressEvent): void {
     this.onProgress?.(event);
   }
+
+  private filterNestedCandidates(
+    candidates: ArtifactCandidate[],
+    entryUrl: string,
+    crawlScope: CrawlScope,
+  ): ArtifactCandidate[] {
+    if (crawlScope === "site") {
+      return candidates;
+    }
+
+    const entryPath = new URL(entryUrl).pathname.toLowerCase();
+    const entryStem = entryPath.replace(/(?:index)?\.html?$/i, "").replace(/\/+$/, "") || entryPath;
+    const entryDirectory = entryPath.includes("/") ? entryPath.slice(0, entryPath.lastIndexOf("/") + 1) : "/";
+
+    return candidates.filter((candidate) => {
+      if (candidate.type !== "html") {
+        return true;
+      }
+
+      const discoveredFrom = candidate.discoveredFrom.toLowerCase();
+      if (discoveredFrom.includes("iframe") || discoveredFrom.includes("form")) {
+        return true;
+      }
+
+      const candidatePath = new URL(candidate.url).pathname.toLowerCase();
+      if (candidatePath === entryPath) {
+        return true;
+      }
+
+      if (entryDirectory !== "/") {
+        return candidatePath.startsWith(entryDirectory);
+      }
+
+      if (entryStem !== entryPath && candidatePath.startsWith(entryStem)) {
+        return true;
+      }
+
+      if (candidatePath.startsWith(`${entryPath}/`)) {
+        return true;
+      }
+
+      return false;
+    });
+  }
 }
 
 export { extractArtifactCandidates };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redstone-md/mapr",
-  "version": "0.0.2-alpha",
+  "version": "0.0.4-alpha",
   "type": "module",
   "description": "Bun-native CLI/TUI for reverse-engineering frontend websites, bundles, WASM, and service workers",
   "license": "SEE LICENSE IN LICENSE",
@@ -30,6 +30,7 @@
     "mapr": "./bin/mapr"
   },
   "files": [
+    "assets",
     "bin",
     "index.ts",
     "lib",