@hraness/slopcamera 3.2.8 → 3.3.2

package/src/capability-manifest.ts

@@ -0,0 +1,361 @@
+import { z } from "zod"
+
+import { canonicalJsonSha256 } from "./code/canonical-json.js"
+import { createBoundedJsonValueSnapshot, deepFreezeJson } from "./code/json-snapshot.js"
+
+export const SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS = Object.freeze({
+  bytes: 4 * 1024 * 1024,
+  commands: 256,
+  evidence: 64,
+  modules: 64,
+  operations: 512,
+  profiles: 128,
+  requirements: 32,
+  tools: 128,
+  workflows: 128,
+})
+
+const identifier = z.string().min(1).max(192).regex(/^[a-z][a-z0-9]*(?:[-_.:/@][a-z0-9]+)*$/u)
+const commandName = z.string().min(1).max(128).regex(/^[a-z][a-z0-9-]*(?: [a-z][a-z0-9-]*){0,3}$/u)
+const digest = z.string().regex(/^[a-f0-9]{64}$/u)
+const positiveSafeInteger = z.number().int().safe().positive()
+const nonnegativeSafeInteger = z.number().int().safe().nonnegative()
+
+export const SlopcameraCapabilityEffectSchema = z.enum([
+  "pure",
+  "local-read",
+  "local-derived-write",
+  "project-mutation",
+  "paid-cloud",
+  "live-control",
+])
+
+export const SlopcameraCapabilityResumeSchema = z.enum([
+  "deterministic",
+  "verified-receipt",
+  "recoverable-transaction",
+  "ambiguous-after-dispatch",
+  "non-resumable-live",
+])
+
+export const SlopcameraCapabilityResourceSchema = z.enum([
+  "cpu",
+  "local-io",
+  "ffmpeg",
+  "vision",
+  "whisper",
+  "network",
+  "paid-call",
+  "project-render",
+  "project-publication",
+  "output-publication",
+  "capture-device",
+  "browser",
+])
+
+export const SlopcameraCapabilityPreparationSchema = z.enum([
+  "project-state",
+  "recording-metadata",
+  "screen-capture",
+  "camera",
+  "microphone",
+  "system-audio",
+  "typed-text",
+  "window-metadata",
+  "local-media",
+  "provider-options",
+])
+
+export const SlopcameraCapabilityOperationSchema = z.strictObject({
+  cache: z.enum(["none", "exact-run", "content-addressed"]),
+  cancellable: z.boolean(),
+  effect: SlopcameraCapabilityEffectSchema,
+  inputSchemaId: identifier,
+  key: z.string().min(3).max(256).regex(/^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*@[1-9][0-9]*$/u),
+  kind: z.string().min(3).max(192).regex(/^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*(?:\.[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*)+$/u),
+  lifecycle: z.enum(["pure", "local-artifact", "project-transaction", "paid-dispatch", "live-control"]),
+  maxDurationMs: positiveSafeInteger,
+  maxFanOut: nonnegativeSafeInteger,
+  maxInputBytes: nonnegativeSafeInteger,
+  maxOutputBytes: nonnegativeSafeInteger,
+  outputSchemaId: identifier,
+  preparation: z.array(SlopcameraCapabilityPreparationSchema).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.requirements),
+  resources: z.array(z.strictObject({
+    amount: positiveSafeInteger,
+    resource: SlopcameraCapabilityResourceSchema,
+  })).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.requirements),
+  resume: SlopcameraCapabilityResumeSchema,
+  version: positiveSafeInteger,
+}).superRefine((operation, context) => {
+  if (operation.key !== `${operation.kind}@${operation.version}`) {
+    context.addIssue({ code: "custom", path: ["key"], message: "Operation key must match kind and version." })
+  }
+  if (new Set(operation.preparation).size !== operation.preparation.length) {
+    context.addIssue({ code: "custom", path: ["preparation"], message: "Operation preparation entries must be unique." })
+  }
+  const resources = operation.resources.map(claim => claim.resource)
+  if (new Set(resources).size !== resources.length) {
+    context.addIssue({ code: "custom", path: ["resources"], message: "Operation resource claims must be unique by resource." })
+  }
+})
+
+export const SlopcameraCapabilityWorkflowSchema = z.strictObject({
+  id: identifier,
+  inputSchemaId: identifier,
+  key: z.string().min(3).max(256).regex(/^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*@[1-9][0-9]*$/u),
+  version: positiveSafeInteger,
+}).superRefine((workflow, context) => {
+  if (workflow.key !== `${workflow.id}@${workflow.version}`) {
+    context.addIssue({ code: "custom", path: ["key"], message: "Workflow key must match id and version." })
+  }
+})
+
+export const SlopcameraCapabilityToolSchema = z.strictObject({
+  destructive: z.boolean(),
+  idempotent: z.boolean(),
+  name: z.string().min(1).max(128).regex(/^[a-z][a-z0-9_]*$/u),
+  openWorld: z.boolean(),
+  readOnly: z.boolean(),
+}).superRefine((tool, context) => {
+  if (tool.readOnly && tool.destructive) {
+    context.addIssue({ code: "custom", message: "A read-only tool cannot be destructive." })
+  }
+})
+
+export const SlopcameraCapabilityCommandSchema = z.strictObject({
+  effect: SlopcameraCapabilityEffectSchema,
+  name: commandName,
+})
+
+export const SlopcameraCapabilityQualificationSchema = z.strictObject({
+  evidence: z.array(z.string().min(1).max(512)).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.evidence),
+  level: z.enum(["unit", "fixture", "browser", "native", "provider"]),
+  status: z.enum(["qualified", "conditional", "not-qualified"]),
+}).superRefine((qualification, context) => {
+  if (qualification.status !== "not-qualified" && qualification.evidence.length === 0) {
+    context.addIssue({ code: "custom", path: ["evidence"], message: "Qualified or conditional profiles require evidence references." })
+  }
+})
+
+export const SlopcameraCapabilityProfileSchema = z.strictObject({
+  id: identifier,
+  kind: z.enum(["renderer", "native-adapter", "provider", "authoring", "interchange"]),
+  qualification: SlopcameraCapabilityQualificationSchema,
+  requirements: z.array(z.strictObject({
+    description: z.string().min(1).max(256),
+    id: identifier,
+    optional: z.boolean(),
+  })).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.requirements),
+})
+
+export const SlopcameraCapabilityModuleDeclarationSchema = z.strictObject({
+  commands: z.array(SlopcameraCapabilityCommandSchema).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.commands),
+  description: z.string().min(1).max(1_024),
+  moduleId: z.string().min(1).max(128).regex(/^slopcamera\.capability\.[a-z][a-z0-9-]*$/u),
+  operationKeys: z.array(z.string().min(3).max(256)).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.operations),
+  profiles: z.array(SlopcameraCapabilityProfileSchema).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.profiles),
+  stability: z.enum(["stable", "experimental"]),
+  title: z.string().min(1).max(160),
+  toolNames: z.array(z.string().min(1).max(128)).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.tools),
+  trust: z.enum(["portable", "local-effects", "trusted-authoring", "native-adapter", "paid-provider"]),
+  version: positiveSafeInteger,
+  workflowKeys: z.array(z.string().min(3).max(256)).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.workflows),
+}).superRefine((module, context) => {
+  if (module.commands.length + module.operationKeys.length + module.profiles.length + module.toolNames.length + module.workflowKeys.length === 0) {
+    context.addIssue({ code: "custom", message: "A capability module must expose at least one command, operation, profile, tool, or workflow." })
+  }
+  for (const [name, values] of [["operationKeys", module.operationKeys], ["toolNames", module.toolNames], ["workflowKeys", module.workflowKeys]] as const) {
+    if (new Set(values).size !== values.length) {
+      context.addIssue({ code: "custom", path: [name], message: `${name} must be unique within a capability module.` })
+    }
+  }
+})
+
+export const SlopcameraCapabilityModuleSchema = z.strictObject({
+  commands: z.array(SlopcameraCapabilityCommandSchema).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.commands),
+  description: z.string().min(1).max(1_024),
+  moduleId: z.string().min(1).max(128).regex(/^slopcamera\.capability\.[a-z][a-z0-9-]*$/u),
+  operations: z.array(SlopcameraCapabilityOperationSchema).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.operations),
+  profiles: z.array(SlopcameraCapabilityProfileSchema).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.profiles),
+  stability: z.enum(["stable", "experimental"]),
+  title: z.string().min(1).max(160),
+  tools: z.array(SlopcameraCapabilityToolSchema).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.tools),
+  trust: z.enum(["portable", "local-effects", "trusted-authoring", "native-adapter", "paid-provider"]),
+  version: positiveSafeInteger,
+  workflows: z.array(SlopcameraCapabilityWorkflowSchema).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.workflows),
+}).superRefine((module, context) => {
+  const identities = [
+    ["commands", module.commands.map(value => value.name)],
+    ["operations", module.operations.map(value => value.key)],
+    ["profiles", module.profiles.map(value => value.id)],
+    ["tools", module.tools.map(value => value.name)],
+    ["workflows", module.workflows.map(value => value.key)],
+  ] as const
+  if (identities.every(([, values]) => values.length === 0)) {
+    context.addIssue({ code: "custom", message: "A capability module must expose at least one command, operation, profile, tool, or workflow." })
+  }
+  for (const [name, values] of identities) {
+    if (new Set(values).size !== values.length) context.addIssue({ code: "custom", path: [name], message: `${name} must be unique within a capability module.` })
+  }
+})
+
+const manifestBodyBaseSchema = z.strictObject({
+  host: z.enum(["portable", "local"]),
+  kind: z.literal("slopcamera.capability-manifest"),
+  modules: z.array(SlopcameraCapabilityModuleSchema).min(1).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.modules),
+  schemaVersion: z.literal(1),
+  toolVersion: z.string().min(1).max(128),
+})
+
+type ManifestBody = z.infer<typeof manifestBodyBaseSchema>
+
+function validateManifestOwnership(manifest: ManifestBody, context: z.RefinementCtx): void {
+  const ownership = new Map<string, string>()
+  for (const [moduleIndex, module] of manifest.modules.entries()) {
+    for (const identity of [
+      module.moduleId,
+      ...module.commands.map(value => `command:${value.name}`),
+      ...module.operations.map(value => `operation:${value.key}`),
+      ...module.profiles.map(value => `profile:${value.id}`),
+      ...module.tools.map(value => `tool:${value.name}`),
+      ...module.workflows.map(value => `workflow:${value.key}`),
+    ]) {
+      const owner = ownership.get(identity)
+      if (owner !== undefined) context.addIssue({ code: "custom", path: ["modules", moduleIndex], message: `${identity} is owned by both ${owner} and ${module.moduleId}.` })
+      ownership.set(identity, module.moduleId)
+    }
+    if (manifest.host === "portable" && module.trust !== "portable") {
+      context.addIssue({ code: "custom", path: ["modules", moduleIndex, "trust"], message: "Portable manifests may contain only portable capability modules." })
+    }
+  }
+}
+
+const manifestBodySchema = manifestBodyBaseSchema.superRefine(validateManifestOwnership)
+
+export const SlopcameraCapabilityManifestSchema = manifestBodyBaseSchema.extend({
+  manifestSha256: digest,
+}).superRefine(validateManifestOwnership)
+
+const compilerInputSchema = z.strictObject({
+  host: z.enum(["portable", "local"]),
+  modules: z.array(SlopcameraCapabilityModuleDeclarationSchema).min(1).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.modules),
+  operations: z.array(SlopcameraCapabilityOperationSchema).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.operations),
+  tools: z.array(SlopcameraCapabilityToolSchema).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.tools),
+  toolVersion: z.string().min(1).max(128),
+  workflows: z.array(SlopcameraCapabilityWorkflowSchema).max(SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.workflows),
+})
+
+export type SlopcameraCapabilityOperation = Readonly<z.infer<typeof SlopcameraCapabilityOperationSchema>>
+export type SlopcameraCapabilityWorkflow = Readonly<z.infer<typeof SlopcameraCapabilityWorkflowSchema>>
+export type SlopcameraCapabilityTool = Readonly<z.infer<typeof SlopcameraCapabilityToolSchema>>
+export type SlopcameraCapabilityModuleDeclaration = Readonly<z.infer<typeof SlopcameraCapabilityModuleDeclarationSchema>>
+export type SlopcameraCapabilityManifest = Readonly<z.infer<typeof SlopcameraCapabilityManifestSchema>>
+
+function compareBy<Key extends string>(key: Key) {
+  return <Value extends Readonly<Record<Key, string>>>(left: Value, right: Value): number => left[key].localeCompare(right[key])
+}
+
+function indexed<Value>(values: readonly Value[], key: (value: Value) => string, label: string): ReadonlyMap<string, Value> {
+  const result = new Map<string, Value>()
+  for (const value of values) {
+    const identity = key(value)
+    if (result.has(identity)) throw new TypeError(`Duplicate ${label}: ${identity}.`)
+    result.set(identity, value)
+  }
+  return result
+}
+
+function assertExactOwnership(label: string, available: ReadonlyMap<string, unknown>, owners: ReadonlyMap<string, string>): void {
+  for (const key of available.keys()) {
+    if (!owners.has(key)) throw new TypeError(`Unowned ${label}: ${key}.`)
+  }
+  for (const key of owners.keys()) {
+    if (!available.has(key)) throw new TypeError(`Unknown ${label} declared by a capability module: ${key}.`)
+  }
+}
+
+export function defineSlopcameraCapabilityModule(input: unknown): SlopcameraCapabilityModuleDeclaration {
+  return deepFreezeJson(SlopcameraCapabilityModuleDeclarationSchema.parse(
+    createBoundedJsonValueSnapshot(input, SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.bytes, "capability module").value,
+  ))
+}
+
+export function compileSlopcameraCapabilityManifest(input: unknown): SlopcameraCapabilityManifest {
+  const parsed = compilerInputSchema.parse(
+    createBoundedJsonValueSnapshot(input, SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.bytes, "capability manifest compiler input").value,
+  )
+  const operations = indexed(parsed.operations, value => value.key, "operation inventory key")
+  const workflows = indexed(parsed.workflows, value => value.key, "workflow inventory key")
+  const tools = indexed(parsed.tools, value => value.name, "tool inventory name")
+  const operationOwners = new Map<string, string>()
+  const workflowOwners = new Map<string, string>()
+  const toolOwners = new Map<string, string>()
+  const moduleIds = new Set<string>()
+  const commandOwners = new Map<string, string>()
+  const profileOwners = new Map<string, string>()
+
+  const claim = (owners: Map<string, string>, key: string, moduleId: string, label: string): void => {
+    const owner = owners.get(key)
+    if (owner !== undefined) throw new TypeError(`${label} ${key} is owned by both ${owner} and ${moduleId}.`)
+    owners.set(key, moduleId)
+  }
+
+  const modules = [...parsed.modules].sort(compareBy("moduleId")).map(module => {
+    if (moduleIds.has(module.moduleId)) throw new TypeError(`Duplicate capability module: ${module.moduleId}.`)
+    moduleIds.add(module.moduleId)
+    for (const command of module.commands) claim(commandOwners, command.name, module.moduleId, "Command")
+    for (const profile of module.profiles) claim(profileOwners, profile.id, module.moduleId, "Profile")
+    const resolvedOperations = module.operationKeys.map(key => {
+      claim(operationOwners, key, module.moduleId, "Operation")
+      const value = operations.get(key)
+      if (value === undefined) throw new TypeError(`Unknown operation declared by ${module.moduleId}: ${key}.`)
+      return value
+    }).sort(compareBy("key"))
+    const resolvedWorkflows = module.workflowKeys.map(key => {
+      claim(workflowOwners, key, module.moduleId, "Workflow")
+      const value = workflows.get(key)
+      if (value === undefined) throw new TypeError(`Unknown workflow declared by ${module.moduleId}: ${key}.`)
+      return value
+    }).sort(compareBy("key"))
+    const resolvedTools = module.toolNames.map(name => {
+      claim(toolOwners, name, module.moduleId, "Tool")
+      const value = tools.get(name)
+      if (value === undefined) throw new TypeError(`Unknown tool declared by ${module.moduleId}: ${name}.`)
+      return value
+    }).sort(compareBy("name"))
+    const { operationKeys: _operationKeys, toolNames: _toolNames, workflowKeys: _workflowKeys, ...metadata } = module
+    return {
+      ...metadata,
+      commands: [...module.commands].sort(compareBy("name")),
+      operations: resolvedOperations,
+      profiles: [...module.profiles].sort(compareBy("id")),
+      tools: resolvedTools,
+      workflows: resolvedWorkflows,
+    }
+  })
+
+  assertExactOwnership("operation", operations, operationOwners)
+  assertExactOwnership("workflow", workflows, workflowOwners)
+  assertExactOwnership("tool", tools, toolOwners)
+  const body = manifestBodySchema.parse({
+    host: parsed.host,
+    kind: "slopcamera.capability-manifest",
+    modules,
+    schemaVersion: 1,
+    toolVersion: parsed.toolVersion,
+  })
+  return deepFreezeJson(SlopcameraCapabilityManifestSchema.parse({
+    ...body,
+    manifestSha256: canonicalJsonSha256(body),
+  }))
+}
+
+export function parseSlopcameraCapabilityManifest(input: unknown): SlopcameraCapabilityManifest {
+  const manifest = SlopcameraCapabilityManifestSchema.parse(
+    createBoundedJsonValueSnapshot(input, SLOPCAMERA_CAPABILITY_MANIFEST_LIMITS.bytes, "capability manifest").value,
+  )
+  const { manifestSha256, ...body } = manifest
+  const actual = canonicalJsonSha256(body)
+  if (actual !== manifestSha256) throw new TypeError(`Capability manifest digest mismatch: expected ${manifestSha256}, received ${actual}.`)
+  return deepFreezeJson(manifest)
+}

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 
-import { writeFile } from "node:fs/promises"
+import { readFile, writeFile } from "node:fs/promises"
 import { resolve } from "node:path"
 import {
   artifactSummary,
@@ -15,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,
@@ -41,6 +52,12 @@ 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>
@@ -69,6 +86,17 @@ 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.
@@ -147,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.")
@@ -190,8 +235,10 @@ const starter = {
 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
 }
@@ -213,10 +260,15 @@ 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")
+    throw new Error("Use slopcamera image vectorize, generate, icon, or gallery")
   }
   if (
     surface === "init" ||
@@ -391,6 +443,172 @@ export async function main(
     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
+  }
+
   if (command === "code") {
     const [subcommand, ...subcommandArgs] = rest
     if (subcommand === "search") {
@@ -474,7 +692,7 @@ 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

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 () => {