@hraness/slopcamera 3.2.7 → 3.3.1

package/src/cli.ts

@@ -1,18 +1,12 @@
 #!/usr/bin/env bun
 
-import { writeFile } from "node:fs/promises"
+import { readFile, writeFile } from "node:fs/promises"
 import { resolve } from "node:path"
-import { createInterface } from "node:readline/promises"
 import {
   artifactSummary,
   checkDiagramFile,
-  desktopStatus,
-  getLatestDesktopRelease,
-  installDesktop,
-  openInDesktop,
   renderDiagramFile,
   runMcpServer,
-  selectDesktopAsset,
   vectorizeImage,
 } from "./index.js"
 import {
@@ -21,6 +15,17 @@ import {
   slopcameraImageModels,
   type SlopcameraImageModel,
 } from "./generate.js"
+import {
+  generateSlopcameraIcon,
+  slopcameraIconMaximumRounds,
+} from "./icon.js"
+import {
+  generateSlopcameraImageGallery,
+  parseSlopcameraGalleryVary,
+  slopcameraGalleryKinds,
+  slopcameraGalleryLimits,
+  type SlopcameraGalleryAxisSpec,
+} from "./image-gallery.js"
 import {
   executeSlopcameraOperation,
   slopcameraOperationCodes,
@@ -32,6 +37,8 @@ import type { HostResourceCoordinator } from "./host-resources.js"
 import { installSkill, type SkillScope, type SkillTarget } from "./skill-install.js"
 import { pathExists } from "./fs.js"
 import { SLOPCAMERA_VERSION } from "./version.js"
+import { reportUsefulResult, type UsefulResultObserver } from "./support-completion.js"
+import { runProductSupportCommand, showProductSupportInvitation, standaloneSupportEnvironment } from "./support.js"
 
 export const slopcameraCliVersion = SLOPCAMERA_VERSION
 
@@ -45,14 +52,17 @@ Usage:
   slopcamera diagram render <file> [--out-dir <directory>] [--config <file>] [--scale <number>]
   slopcamera image vectorize <image> --output <file.svg> [--json] [--duotone <#rgb,#rgb>]
   slopcamera image generate <prompt> --output <file.png|jpg|webp> [--model <provider/model>] [--json]
+  slopcamera image icon <subject> --output <file.svg> [--purpose <mark|illustration>]
+    [--model <provider/model>] [--ink <#rgb|#rrggbb>] [--rounds <1-${slopcameraIconMaximumRounds}>]
+    [--critique-model <provider/model>] [--keep-raster] [--json]
+  slopcamera image gallery <subject> --output-dir <directory> [--kind <${slopcameraGalleryKinds.join("|")}>]
+    [--count <1-${slopcameraGalleryLimits.candidates}>] [--vary <axis[=v1,v2][;axis...]>] [--candidates <file.json>]
+    [--model <provider/model>] [--cell <${slopcameraGalleryLimits.cellEdgeMin}-${slopcameraGalleryLimits.cellEdgeMax}>] [--tile|--no-tile] [--json]
   slopcamera code search [query] [--limit <number>]
   slopcamera code execute <operation> --input <JSON>
   slopcamera mcp --root <workspace>
-  slopcamera canvas open <file.tldr|file.tldraw>
-  slopcamera canvas status
-  slopcamera canvas url
-  slopcamera canvas install [--yes] [--download-only]
   slopcamera doctor
+  slopcamera support [--json|protocol --json|offer --json|shown <id>|release <id>|dismiss|snooze|enable|status --json]
   slopcamera skill path
   slopcamera skill install [--target codex|claude|agents] [--scope user|project] [--force]
 
@@ -63,9 +73,8 @@ Render writes the same five replaceable artifacts on every run:
   <name>.light.png
   <name>.dark.png
 
-The .tldr file is editable tldraw interchange. It imports into tldraw Offline,
-which can save the newer app-owned .tldraw bundle. Rendering does not require
-tldraw Offline or the tldraw SDK.
+  The .tldr file is editable interchange for browser-based canvas tooling.
+  Rendering does not require a desktop application or a bundled UI runtime.
 
 Vectorize adaptively traces a raster with a checksum-pinned VTracer binary.
 It enforces bounded input, decode, time, path, and output budgets and emits a
@@ -77,6 +86,21 @@ Set AI_GATEWAY_API_KEY, or run through \`vercel env run -- …\` so
 VERCEL_OIDC_TOKEN is available. Slopcamera never stores or prints the token.
 PNG, JPEG, and WebP responses are signature-checked and published atomically.
 
+Icon produces isometric line-art SVG: a style-locked Gateway raster is
+normalized to canonical ink-on-transparent pixels, traced by the local
+vectorizer, and (when --rounds exceeds 1) critiqued by a vision model whose
+feedback revises the prompt for the next attempt. Only Slopcamera's own
+generated output is uploaded for critique — never user media.
+
+Gallery generates several bounded candidates in parallel and composes them
+into one labelled contact sheet plus a receipt. Use it to review texture,
+skybox, backdrop, sprite, or design alternatives, then promote a chosen
+candidate file explicitly — nothing is applied automatically.
+
+Optional support: after useful work, agents can read slopcamera support protocol --json.
+Discovery uses stderr without claiming an invitation; HRANESS_SUPPORT_AUDIENCE=off disables it.
+No feature requires payment. Imported CLI/SDK calls and probes stay quiet.
+
 Code mode searches and executes a fixed semantic registry. Execute accepts
 typed JSON for one exact owned operation code; it never evaluates source text.
 
@@ -151,6 +175,23 @@ function parseDuotone(value: string | undefined): readonly [string, string] | un
   return [colors[0]!, colors[1]!]
 }
 
+function parseGalleryVary(value: string | undefined): readonly SlopcameraGalleryAxisSpec[] | undefined {
+  if (value === undefined) return undefined
+  return parseSlopcameraGalleryVary(value)
+}
+
+async function readGalleryCandidates(path: string): Promise<unknown> {
+  const text = await readFile(resolve(path), "utf8")
+  if (Buffer.byteLength(text, "utf8") > 64 * 1024) {
+    throw new Error("--candidates JSON must be no more than 65536 UTF-8 bytes")
+  }
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error("--candidates must be valid JSON")
+  }
+}
+
 function printFindings(findings: Awaited<ReturnType<typeof checkDiagramFile>>["findings"]): void {
   if (findings.length === 0) {
     console.log("No diagram lint findings.")
@@ -191,24 +232,13 @@ const starter = {
   edges: [{ id: "source-result", from: "source", to: "result" }],
 }
 
-async function confirmInstall(): Promise<boolean> {
-  if (!process.stdin.isTTY) {
-    throw new Error("Pass --yes to download the 100–230 MB official tldraw Offline installer")
-  }
-  const prompt = createInterface({ input: process.stdin, output: process.stdout })
-  try {
-    const answer = await prompt.question(
-      "Download, verify, and launch the official tldraw Offline installer? [y/N] ",
-    )
-    return answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes"
-  } finally {
-    prompt.close()
-  }
-}
-
 export interface SlopcameraCliDependencies {
+  readonly onUsefulResult?: UsefulResultObserver
+  readonly supportEnvironment?: Readonly<Record<string, string | undefined>>
+  readonly gallery?: typeof generateSlopcameraImageGallery
   readonly generate?: typeof generateSlopcameraImageFile
   readonly hostResourceCoordinator?: HostResourceCoordinator
+  readonly icon?: typeof generateSlopcameraIcon
   readonly log?: (value: string) => void
   readonly vectorize?: typeof vectorizeImage
 }
@@ -230,26 +260,22 @@ function canonicalArguments(args: readonly string[]): readonly string[] {
     throw new Error("Use slopcamera diagram init, check, or render")
   }
   if (surface === "image") {
-    if (subcommand === "vectorize" || subcommand === "generate") {
+    if (
+      subcommand === "vectorize" ||
+      subcommand === "generate" ||
+      subcommand === "icon" ||
+      subcommand === "gallery"
+    ) {
       return [subcommand, ...rest]
     }
-    throw new Error("Use slopcamera image vectorize or generate")
-  }
-  if (surface === "canvas") {
-    if (subcommand === "open") return ["open", ...rest]
-    if (subcommand === "status" || subcommand === "url" || subcommand === "install") {
-      return ["desktop", subcommand, ...rest]
-    }
-    throw new Error("Use slopcamera canvas open, status, url, or install")
+    throw new Error("Use slopcamera image vectorize, generate, icon, or gallery")
   }
   if (
     surface === "init" ||
     surface === "check" ||
     surface === "render" ||
     surface === "vectorize" ||
-    surface === "generate" ||
-    surface === "open" ||
-    surface === "desktop"
+    surface === "generate"
   ) {
     throw new Error(`The flat \`${surface}\` command moved to a namespaced Slopcamera surface.\n\n${help}`)
   }
@@ -260,6 +286,11 @@ export async function main(
   args: readonly string[],
   dependencies: SlopcameraCliDependencies = {},
 ): Promise<void> {
+  if (args[0] === "support") {
+    process.exitCode = await runProductSupportCommand(args.slice(1),
+      dependencies.supportEnvironment === undefined ? {} : { env: dependencies.supportEnvironment })
+    return
+  }
   const [command, ...rest] = canonicalArguments(args)
   if (command === undefined || command === "help" || command === "--help" || command === "-h") {
     console.log(help)
@@ -276,6 +307,7 @@ export async function main(
     if (await pathExists(filePath)) throw new Error(`Refusing to overwrite existing file: ${filePath}`)
     await writeFile(filePath, `${JSON.stringify(starter, null, 2)}\n`)
     console.log(`Created ${filePath}`)
+    reportUsefulResult(dependencies.onUsefulResult)
     return
   }
 
@@ -317,6 +349,7 @@ export async function main(
     )
     console.log(artifactSummary(result.artifacts))
     printFindings(result.findings)
+    reportUsefulResult(dependencies.onUsefulResult)
     return
   }
 
@@ -365,6 +398,7 @@ export async function main(
           + `${result.receipt.profile}/${result.receipt.representation}: ${result.outputPath}`,
       )
     }
+    reportUsefulResult(dependencies.onUsefulResult)
     return
   }
 
@@ -405,6 +439,173 @@ export async function main(
         `Generated ${result.mediaType} with ${result.model}: ${result.outputPath} (${result.bytes} bytes, request ${result.requestId})`,
       )
     }
+    reportUsefulResult(dependencies.onUsefulResult)
+    return
+  }
+
+  if (command === "icon") {
+    const parsed = parseArguments(
+      rest,
+      new Set(["model", "output", "ink", "purpose", "rounds", "critique-model"]),
+    )
+    const unknownFlags = [...parsed.flags].filter(
+      (flag) => flag !== "json" && flag !== "keep-raster",
+    )
+    if (unknownFlags.length > 0) {
+      throw new Error(`Unknown icon option: --${unknownFlags[0]}`)
+    }
+    if (parsed.positionals.length !== 1) {
+      throw new Error("slopcamera image icon accepts exactly one subject")
+    }
+    const output = requiredOption(parsed, "output")
+    if (!output.toLowerCase().endsWith(".svg")) {
+      throw new Error("--output must end in .svg")
+    }
+    const model = parsed.options.model ?? slopcameraImageModels[1]
+    if (
+      model.length > 256 ||
+      !/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._:-]*$/iu.test(model)
+    ) {
+      throw new Error(
+        "--model must be a bounded Vercel AI Gateway provider/model id",
+      )
+    }
+    const critiqueModel = parsed.options["critique-model"]
+    if (
+      critiqueModel !== undefined &&
+      (critiqueModel.length > 256 ||
+        !/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._:-]*$/iu.test(critiqueModel))
+    ) {
+      throw new Error(
+        "--critique-model must be a bounded Vercel AI Gateway provider/model id",
+      )
+    }
+    const ink = parsed.options.ink
+    if (ink !== undefined && !/^#[a-f0-9]{3}(?:[a-f0-9]{3})?$/iu.test(ink)) {
+      throw new Error("--ink must be a #rgb or #rrggbb color")
+    }
+    const purpose = parsed.options.purpose
+    if (purpose !== undefined && purpose !== "mark" && purpose !== "illustration") {
+      throw new Error("--purpose must be mark or illustration")
+    }
+    const rounds = parsePositiveInteger(parsed.options.rounds, "rounds")
+    if (rounds !== undefined && rounds > slopcameraIconMaximumRounds) {
+      throw new Error(`--rounds must be at most ${slopcameraIconMaximumRounds}`)
+    }
+    const result = await withSlopcameraOperationHostAdmission(
+      "slopcamera.image.icon",
+      async (lease) => await (dependencies.icon ?? generateSlopcameraIcon)({
+        keepRaster: parsed.flags.has("keep-raster"),
+        model,
+        outputPath: output,
+        subject: requiredPositional(parsed, 0, "subject"),
+        inheritedFileDescriptors: [lease.inheritedFileDescriptor],
+        ...(critiqueModel === undefined ? {} : { critiqueModel }),
+        ...(ink === undefined ? {} : { ink }),
+        ...(purpose === undefined ? {} : { purpose }),
+        ...(rounds === undefined ? {} : { rounds }),
+      }),
+      hostAdmissionOptions(dependencies),
+    )
+    if (parsed.flags.has("json")) {
+      ;(dependencies.log ?? console.log)(JSON.stringify(result, null, 2))
+    } else {
+      const scored = result.attempts
+        .map((attempt) =>
+          attempt.score === undefined
+            ? `#${attempt.round}`
+            : `#${attempt.round}=${attempt.score}`,
+        )
+        .join(" ")
+      ;(dependencies.log ?? console.log)(
+        `Icon ${result.svgSha256.slice(0, 12)} round ${result.selectedRound}/${result.attempts.length} (${scored}): ${result.outputPath}`,
+      )
+    }
+    return
+  }
+
+  if (command === "gallery") {
+    const parsed = parseArguments(
+      rest,
+      new Set(["model", "output-dir", "kind", "count", "vary", "candidates", "cell", "timeout-ms"]),
+    )
+    const unknownFlags = [...parsed.flags].filter(
+      (flag) => flag !== "json" && flag !== "tile" && flag !== "no-tile",
+    )
+    if (unknownFlags.length > 0) {
+      throw new Error(`Unknown gallery option: --${unknownFlags[0]}`)
+    }
+    if (parsed.flags.has("tile") && parsed.flags.has("no-tile")) {
+      throw new Error("--tile and --no-tile are mutually exclusive")
+    }
+    if (parsed.positionals.length !== 1) {
+      throw new Error("slopcamera image gallery accepts exactly one subject")
+    }
+    const model = parsed.options.model ?? slopcameraImageModels[1]
+    if (
+      model.length > 256 ||
+      !/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._:-]*$/iu.test(model)
+    ) {
+      throw new Error(
+        "--model must be a bounded Vercel AI Gateway provider/model id",
+      )
+    }
+    const kind = parsed.options.kind
+    if (kind !== undefined && !slopcameraGalleryKinds.includes(kind as never)) {
+      throw new Error(`--kind must be one of: ${slopcameraGalleryKinds.join(", ")}`)
+    }
+    const count = parsePositiveInteger(parsed.options.count, "count")
+    if (count !== undefined && count > slopcameraGalleryLimits.candidates) {
+      throw new Error(`--count must be at most ${slopcameraGalleryLimits.candidates}`)
+    }
+    const cell = parsePositiveInteger(parsed.options.cell, "cell")
+    if (
+      cell !== undefined &&
+      (cell < slopcameraGalleryLimits.cellEdgeMin || cell > slopcameraGalleryLimits.cellEdgeMax)
+    ) {
+      throw new Error(
+        `--cell must be between ${slopcameraGalleryLimits.cellEdgeMin} and ${slopcameraGalleryLimits.cellEdgeMax}`,
+      )
+    }
+    const timeoutMs = parsePositiveInteger(parsed.options["timeout-ms"], "timeout-ms")
+    const vary = parseGalleryVary(parsed.options.vary)
+    const candidates = parsed.options.candidates === undefined
+      ? undefined
+      : await readGalleryCandidates(parsed.options.candidates)
+    if (candidates !== undefined && !Array.isArray(candidates)) {
+      throw new Error("--candidates JSON must be an array of {id, prompt|variant} entries")
+    }
+    const result = await withSlopcameraOperationHostAdmission(
+      "slopcamera.image.gallery",
+      async () => await (dependencies.gallery ?? generateSlopcameraImageGallery)({
+        subject: requiredPositional(parsed, 0, "subject"),
+        outputDir: requiredOption(parsed, "output-dir"),
+        model,
+        ...(kind === undefined ? {} : { kind }),
+        ...(count === undefined ? {} : { count }),
+        ...(vary === undefined ? {} : { vary }),
+        ...(candidates === undefined ? {} : { candidates }),
+        ...(cell === undefined ? {} : { cellEdge: cell }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        ...(parsed.flags.has("tile")
+          ? { tiled: true }
+          : parsed.flags.has("no-tile") ? { tiled: false } : {}),
+      }),
+      hostAdmissionOptions(dependencies),
+    )
+    if (parsed.flags.has("json")) {
+      ;(dependencies.log ?? console.log)(JSON.stringify(result, null, 2))
+    } else {
+      const rows = result.candidates.map(candidate =>
+        candidate.status === "generated"
+          ? `#${candidate.index} ${candidate.id}\t${candidate.path}`
+          : `#${candidate.index} ${candidate.id}\tfailed`)
+      ;(dependencies.log ?? console.log)(
+        `Gallery ${result.counts.generated}/${result.counts.requested} generated (${result.model}): ${result.gallery.path}\n`
+          + `${rows.join("\n")}\nreceipt ${result.receiptPath}`,
+      )
+    }
+    reportUsefulResult(dependencies.onUsefulResult)
     return
   }
 
@@ -460,6 +661,9 @@ export async function main(
       ;(dependencies.log ?? console.log)(
         JSON.stringify({ operation, result }, null, 2),
       )
+      if (operation === "slopcamera.diagram.render" || operation === "slopcamera.image.vectorize" || operation === "slopcamera.image.generate") {
+        reportUsefulResult(dependencies.onUsefulResult)
+      }
       return
     }
     throw new Error(
@@ -479,15 +683,7 @@ export async function main(
     return
   }
 
-  if (command === "open") {
-    const parsed = parseArguments(rest, new Set())
-    await openInDesktop(requiredPositional(parsed, 0, "tldraw file"))
-    console.log("Opened in tldraw Offline.")
-    return
-  }
-
   if (command === "doctor") {
-    const status = await desktopStatus()
     console.log(`slopcamera ${slopcameraCliVersion}`)
     console.log(`Bun ${process.versions.bun ?? "not detected"}`)
     console.log("Headless diagram SVG/PNG/tldraw renderer ready")
@@ -496,67 +692,16 @@ export async function main(
         ? "Local raster-to-SVG vectorizer unavailable on Windows (fails closed with tool_platform)"
         : "Local raster-to-SVG vectorizer ready without authentication (VTracer downloads on first use)",
     )
-    console.log("Root-relative MCP check/render server ready (trusted local workspace)")
+    console.log("Root-relative MCP check/render/scene server ready (trusted local workspace)")
     const gateway = slopcameraGatewayCredentialStatus()
     console.log(
       gateway.available
         ? `Vercel AI Gateway ready via ${gateway.source}`
         : "Vercel AI Gateway requires AI_GATEWAY_API_KEY or VERCEL_OIDC_TOKEN",
     )
-    console.log(
-      status.installedPath === null
-        ? "tldraw Offline not installed (optional)"
-        : `tldraw Offline: ${status.installedPath}`,
-    )
-    console.log(
-      status.server === null
-        ? "tldraw Offline agent server not running (optional)"
-        : `tldraw Offline agent server: localhost:${status.server.port}`,
-    )
     return
   }
 
-  if (command === "desktop") {
-    const [subcommand, ...subcommandArgs] = rest
-    if (subcommand === "status") {
-      const status = await desktopStatus()
-      console.log(JSON.stringify(status, null, 2))
-      return
-    }
-    if (subcommand === "url") {
-      const release = await getLatestDesktopRelease()
-      const asset = selectDesktopAsset(release)
-      console.log(
-        JSON.stringify(
-          {
-            release: release.tag_name,
-            releaseUrl: release.html_url,
-            asset: asset.name,
-            url: asset.browser_download_url,
-            bytes: asset.size,
-            sha256: asset.digest,
-          },
-          null,
-          2,
-        ),
-      )
-      return
-    }
-    if (subcommand === "install") {
-      const parsed = parseArguments(subcommandArgs, new Set())
-      if (!parsed.flags.has("yes") && !(await confirmInstall())) {
-        console.log("Cancelled.")
-        return
-      }
-      const result = await installDesktop({ downloadOnly: parsed.flags.has("download-only") })
-      console.log(
-        `${parsed.flags.has("download-only") ? "Downloaded" : "Prepared"} tldraw Offline ${result.release}: ${result.filePath}`,
-      )
-      return
-    }
-    throw new Error("Use slopcamera canvas status, url, or install")
-  }
-
   if (command === "skill") {
     const [subcommand, ...subcommandArgs] = rest
     if (subcommand === "path") {
@@ -593,7 +738,10 @@ export async function main(
 
 if (import.meta.main) {
   try {
-    await main(process.argv.slice(2))
+    const env = standaloneSupportEnvironment()
+    let usefulResult = false
+    await main(process.argv.slice(2), { supportEnvironment: env, onUsefulResult: () => { usefulResult = true } })
+    if (usefulResult && (process.exitCode ?? 0) === 0) await showProductSupportInvitation({ env })
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error))
     process.exitCode = 1

package/src/code/canonical-json.ts

@@ -19,6 +19,15 @@ const MAX_CANONICAL_JSON_BYTES = Number.MAX_SAFE_INTEGER
 const MAX_CANONICAL_JSON_DEPTH = Number.MAX_SAFE_INTEGER
 const MAX_CANONICAL_JSON_VALUES = Number.MAX_SAFE_INTEGER
 
+// Cross-implementation parity (pinned byte- and digest-for-digest by
+// canonical-parity.test.ts): on the shared domain — finite numbers other
+// than -0, well-formed UTF-16 strings, dense arrays, and plain objects
+// with enumerable string data properties — canonicalJson is identical to
+// @hraness/oh's RFC 8785 canonicalizer. Slopcamera intentionally keeps a
+// wider domain that oh rejects: -0 normalizes to 0, unpaired surrogates
+// serialize through \uXXXX escapes, non-enumerable own properties and
+// non-index array properties are ignored, and the iterative traversal
+// accepts nesting far beyond oh's recursive stack range.
 export type CanonicalJsonValue =
   | JsonScalar
   | readonly CanonicalJsonValue[]

package/src/generate.ts

@@ -116,7 +116,7 @@ function environment(
   return injected ?? process.env
 }
 
-function resolveGatewayCredential(
+export function resolveSlopcameraGatewayCredential(
   injected: SlopcameraEnvironment | undefined,
 ): Readonly<{
   source: SlopcameraGatewayCredentialSource
@@ -588,7 +588,7 @@ async function performGeneration(
 }>> {
   const model = validateModel(input.model)
   const prompt = validatePrompt(input.prompt)
-  const credential = resolveGatewayCredential(dependencies.environment)
+  const credential = resolveSlopcameraGatewayCredential(dependencies.environment)
   const timeout = combineSignals(input.signal, validateTimeout(input.timeoutMs))
   try {
     const generation = (async () => {