@melite/image-upscale-tools 0.1.4-alpha → 0.2.0-alpha

package/README.md

@@ -0,0 +1,36 @@
+---
+description: Hidden upscale card running SeedVR2 over an input image, with consumed fragment arms for resize, pixel-upscale, RTX VSR, and concat.
+kind: package-library
+---
+
+# @melite/image-upscale-tools
+
+`@melite/image-upscale-tools` is the upscale card (`id: 'upscale-tools'`, stage row `generate`): SeedVR2-3B fp16 diffusion upscaling on a required `input_image`. It boards the `seedvr2-ema` family's declared `upscale` action and requires the `ComfyUI-SeedVR2_VideoUpscaler`, `ComfyUI-KJNodes`, and `Nvidia_RTX_Nodes_ComfyUI` packs. The package's single source module is the root face the cardPackages SSOT composes (`@melite/image-upscale-tools`); there is no tool or client face. The card is hidden from the sidebar (image order 16) and additionally serves the consumed tool fragments — `resize`, `pixel-upscale`, `rtx-vsr`, `concat`, and `input` — each with its own arm.
+
+## Contract
+
+- `.` — the card definition and registration (the root module carries `inject = ['comfyui']`). Schema: `input_image` (required, path); ride keys with hint-only ranges and NO defaults — `resolution` (256..2160), `max_resolution` (512..4096), `batch_size` (1..16), where the model row owns the values (1080/4096/1); and `seed` (default −1). There are NO `dit_model`/`vae_model` knobs — weights ride the lane's `unet`/`vae` inputs. The `rtx-vsr` arm is compose-truth only: it emits the graph, while execution requires the NVIDIA SDK stack. `admits: ['filename_prefix']`; `spells: ['input_image']` — a `$spell` value (the `$image` form) names a wired stage input that rides verbatim. Estate-file contract: a file param must exist at compose (absolute mount path); a linked upstream output arrives as an asset URL (`/v1/assets/runs/...`) and the submit-time uploader stages it, refusing loudly on a dead URL.
+- `./package.json` — the manifest.
+
+## Model Experience
+
+### Request context and condition
+
+A run conditions the upscale graph only when the card composes; no agent tool face ships.
+
+#### What the model sees
+
+SeedVR2 receives the staged image plus the gated resolution, batch, and seed values as graph inputs.
+
+#### Token effect
+
+zero-direct — the package contributes no prompt or schema to any language-model context.
+
+#### KV Cache effect
+
+independent — nothing here appends to or reshapes a session cache.
+
+## Known Limitations and Deferred Work
+
+- **rtx-vsr needs the NVIDIA SDK** — the arm composes anywhere but executes only where the RTX stack exists.
+- **No dit/vae knobs** — weight selection rides the model row; a card-level override is not declared.

package/lib/card.d.ts

@@ -1,4 +1,4 @@
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context } from '@melite/comfyui-card-kit/card-definition';
 import type { ModelFacts } from '@melite/comfyui-card-kit/facts';
 import type { GraphBuilder } from '@melite/comfyui-card-kit/graph';
 export declare const ACTION_BINDINGS: Record<string, (p: Record<string, unknown>, model: ModelFacts, g: GraphBuilder, runId: string) => void>;

package/lib/card.js

@@ -2,10 +2,11 @@ import { existsSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import z from '@deepseek-ai/schemastery';
 import { declaredAction, instantiateAction } from '@melite/comfyui-card-kit';
-import { resolveLinkedInput } from '@melite/comfyui-cordis/linked';
+import { resolveLinkedInput, runMediaPrefix } from '@melite/comfyui-card-kit/linked';
 import { bag } from '@melite/contracts/extraKeys';
-import { DECL as seedvr2Decl } from '@melite/models-seedvr2_ema';
-import { gatedResolve } from '@melite/comfyui-cordis';
+import { DECL as seedvr2Decl } from '@melite/models-seedvr2-ema';
+import { inputImageExtra, seedExtra } from '@melite/comfyui-card-kit/fields';
+import { callableSchema, gatedResolve } from '@melite/comfyui-card-kit/admission';
 // THE FAMILY BINDINGS (the atom vocabulary, stroke 3): the declared
 // action composes; the legacy kit lane stays the declared fallback
 // (byte-oracle + unbound-row safety). Keyed by OWNING FAMILY
@@ -17,10 +18,10 @@ export const ACTION_BINDINGS = {
     },
 };
 const schema = z.object({
-    input_image: z.string().role('path').description("Input image").extra('extra', bag({ order: 0, group: "input", width: 1, tooltip: "The frame to restore. Absolute mount path.", required: true, wtype: 'image', })),
+    input_image: z.string().role('path').description("Input image").extra('extra', bag(inputImageExtra({ tooltip: 'The frame to restore. Absolute mount path.' }))),
     // ride-the-model keys (ABSENT: no schema default — the
     // compose-door cascade overlays model defaults, then explicit
-    // params): resolution/max_resolution/batch_size ride the seedvr2_ema
+    // params): resolution/max_resolution/batch_size ride the seedvr2-ema
     // model row (1080/4096/1); seed rides -1 (model row carries 0,
     // explicit wins — an explicit 42 rides the model row). RANGE RULE
     
@@ -30,18 +31,13 @@ const schema = z.object({
     resolution: z.number().description("Target short side").min(256).max(2160).step(2).extra('extra', bag({ order: 0, group: "target", columns: 2, width: 1, tooltip: "1080 = FHD rail. SeedVR2 redraws detail at this size.", wtype: 'number' })),
     max_resolution: z.number().description("Max resolution").min(512).max(4096).step(64).extra('extra', bag({ order: 1, group: "target", columns: 2, width: 1, tooltip: "The hard ceiling — inputs already past it pass through.", wtype: 'number' })),
     batch_size: z.number().description("Batch size").min(1).max(16).step(1).extra('extra', bag({ order: 0, group: "run", width: 1, tooltip: "Video frames ride batches; images are batch 1.", wtype: 'number' })),
-    seed: z.number().description("Seed").step(1).default(-1).extra('extra', bag({ order: 1, group: "run", width: 1 })),
+    seed: z.number().description("Seed").step(1).default(-1).extra('extra', bag(seedExtra({ order: 1, group: 'run', width: 1 }))),
     // NO dit_model/vae_model (card declares no such knobs — the
     // weights ride lane_inputs.unet/vae; old drafts naming them still
     // parse via the door's non-strict overlay but compose never reads
     // them).
 });
-/** The schema's callable face — ONE cast serving both seams (the
- *  registration's schema carrier and the compose strict resolve's
- *  judge): schemastery schemas are callable (Schema.resolve) but
- *  carry a typed data parameter, while both card-seam consumers
- *  take unknown. */
-const schemaFn = schema;
+const schemaFn = callableSchema(schema);
 export const inject = ['comfyui'];
 
 // identity ring; the card owns its label/description/genre/icon).
@@ -58,6 +54,17 @@ export const identity = {
         'rtx-vsr is NVIDIA-SDK-only: the arm is compose-truth, execution needs the RTX stack',
     ],
 };
+/** The estate's own tree for the linked-input rewrite — the
+ *  compose call's manifest, first entry (the queue's own root).
+ *  A root-relative ref with no manifest refuses LOUD (there is no
+ *  cwd guess to fall back on — J12 killed it). */
+function estateRoot(estate) {
+    const first = estate?.stateRoots[0];
+    if (first === undefined || first === '') {
+        throw new Error("linked input needs the estate state root — compose with the queue seat's roots manifest (a root-relative asset URL cannot be resolved from the cwd; it never guesses)");
+    }
+    return first;
+}
 export function apply(ctx) {
     ctx.effect(() => ctx.comfyui.registerCard({
         id: 'upscale-tools',
@@ -82,7 +89,7 @@ export function apply(ctx) {
         admits: ['filename_prefix'],
         spells: ['input_image'],
         schema: schemaFn,
-        compose(p, model, g, runId) {
+        compose(p, model, g, runId, estate) {
             // THE SCHEMA GATE (the audio-trio admission precedent — the
             // card's own declaration validates the last hop into the
             // engine): schemastery walk enforces declared types + bounds
@@ -109,7 +116,12 @@ export function apply(ctx) {
             // uploader fetches them); root-relative URLs rewrite to the
             // runs-root mount path (same estate, verified NOW).
             // Compile-time, never inference-time.
-            const ref = resolveLinkedInput(String(doc.input_image).trim());
+            // J12: a root-relative asset URL resolves against the estate's
+            // config-named trees (the compose call's manifest — first tree
+            // is the queue's own root); every other spelling rides without
+            // a seat read. The retired env seam's cwd guess never returns.
+            const raw = String(doc.input_image).trim();
+            const ref = runMediaPrefix(raw) === '' ? raw : resolveLinkedInput(raw, estateRoot(estate));
             doc.input_image = ref;
             const lower = ref.toLowerCase();
             if (!ref.startsWith('$') && !lower.startsWith('http://') && !lower.startsWith('https://')) {
@@ -122,7 +134,7 @@ export function apply(ctx) {
             if (bound)
                 bound(doc, model, g, runId);
             else {
-                throw new Error(`no declared action for family '${String(model.family ?? model.id)}' on the upscale-tools card — every boarded family (seedvr2_ema) composes its own declared segment; this address owns none`);
+                throw new Error(`no declared action for family '${String(model.family ?? model.id)}' on the upscale-tools card — every boarded family (seedvr2-ema) composes its own declared segment; this address owns none`);
             }
         },
     }));

package/package.json

@@ -1,26 +1,29 @@
 {
-  "version": "0.1.4-alpha",
-  "license": "SSPL-1.0",
+  "version": "0.2.0-alpha",
+  "license": "AGPL-3.0-or-later",
   "type": "module",
-  "description": "the upscale-tools card (the image lane) — one card one package: card.ts host face + ui/ studio + agents/ context",
+  "description": "the upscale-tools card (the image lane) — one card one package: card.ts host face + agents/ context (no tool face, no ui/ — the view is constructed by @melite/card-base from the emission)",
   "exports": {
     ".": {
       "types": "./lib/card.d.ts",
       "default": "./lib/card.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./card": {
+      "types": "./lib/card.d.ts",
+      "default": "./lib/card.js"
+    }
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.4",
-    "@melite/comfyui-card-kit": "0.1.4-alpha",
-    "@melite/comfyui-cordis": "0.1.4-alpha",
-    "@melite/contracts": "0.1.4-alpha",
-    "@melite/models-seedvr2_ema": "0.1.4-alpha"
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "@melite/comfyui-card-kit": "0.2.0-alpha",
+    "@melite/contracts": "0.2.0-alpha",
+    "@melite/models-seedvr2-ema": "0.2.0-alpha"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "typescript": "^5.9.3",
-    "@deepseek-ai/cordis": "^4.0.4"
+    "@deepseek-ai/cordis": "^4.0.5"
   },
   "name": "@melite/image-upscale-tools",
   "files": [
@@ -29,7 +32,7 @@
     "lib/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4"
+    "@deepseek-ai/cordis": "^4.0.5"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",